@carlonicora/nextjs-jsonapi 3.24.2 → 3.26.0

package/dist/features/analytics/index.d.mts

@@ -0,0 +1,508 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { A as ApiDataInterface, J as JsonApiHydratedDataInterface } from '../../ApiDataInterface-BcZeXy5X.mjs';
+import { U as UserInterface } from '../../user.interface-CSaGWFbg.mjs';
+import { A as AbstractApiData } from '../../AbstractApiData-XLhBP5Tl.mjs';
+import { A as AbstractService, N as NextRef } from '../../AbstractService-Ckm2X5fW.mjs';
+export { a as analyticsModules } from '../../analytics.modules-pzGwMASI.mjs';
+import '../../feature.interface-CXb1-vNq.mjs';
+import '../../ApiRequestDataTypeInterface-CYEcRUrh.mjs';
+import '../../types-D0uLYV2P.mjs';
+import 'lucide-react';
+
+type AnalyticsTrackerProps = {
+    hasConsent: boolean;
+    resolveSection: (pathname: string) => "public" | "app";
+    sensitivePrefixes?: string[];
+};
+declare function AnalyticsTracker({ hasConsent, resolveSection, sensitivePrefixes }: AnalyticsTrackerProps): null;
+
+interface AnalyticsBreakdownInterface extends ApiDataInterface {
+    get dimension(): string;
+    get key(): string;
+    get visitors(): number;
+    get sessions(): number;
+    get pageViews(): number;
+}
+
+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;
+}
+
+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;
+}
+
+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;
+}
+
+declare const ANALYTICS_SECTIONS: readonly ["all", "public", "app"];
+type AnalyticsSection = (typeof ANALYTICS_SECTIONS)[number];
+declare const ANALYTICS_GRANULARITIES: readonly ["day", "week", "month"];
+type AnalyticsGranularity = (typeof ANALYTICS_GRANULARITIES)[number];
+declare const ANALYTICS_DIMENSIONS: readonly ["source", "medium", "campaign", "referrer", "route", "landing"];
+type AnalyticsDimension = (typeof ANALYTICS_DIMENSIONS)[number];
+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`. */
+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;
+};
+type AnalyticsSummaryInput = {
+    id: string;
+    section: string;
+    window: string;
+    visitors: number;
+    sessions: number;
+    pageViews: number;
+    pagesPerSession: number;
+    consentShare: number;
+};
+type AnalyticsTimelineInput = {
+    id: string;
+    /** Backend field type is "date" — emitted via formatLocalDate, never raw. */
+    bucket: Date;
+    section: string;
+    visitors: number;
+    sessions: number;
+    pageViews: number;
+};
+type AnalyticsBreakdownInput = {
+    id: string;
+    dimension: string;
+    key: string;
+    visitors: number;
+    sessions: number;
+    pageViews: number;
+};
+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;
+};
+type AnalyticsPageViewInput = {
+    id: string;
+    /** Backend field type is "datetime" — emitted via toISOString(). */
+    createdAt: Date;
+    path: string;
+    route: string;
+    section: string;
+};
+
+type AnalyticsAdminFilterState = {
+    /** ISO 8601 instant. */
+    from: string;
+    /** ISO 8601 instant. */
+    to: string;
+    section: AnalyticsSection;
+    granularity: AnalyticsGranularity;
+};
+interface AnalyticsAdminContextType {
+    /** The six summary rows: {public, app, total} × {current, previous}. */
+    summary: AnalyticsSummaryInterface[];
+    timeline: AnalyticsTimelineInterface[];
+    breakdowns: Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>;
+    sessions: AnalyticsSessionInterface[];
+    filters: AnalyticsAdminFilterState;
+    /** Merges a partial patch into the current filters; every key is optional. */
+    setFilters: (next: Partial<AnalyticsAdminFilterState>) => void;
+    /** Appends the next page of sessions; a no-op when there is none. */
+    loadMoreSessions: () => Promise<void>;
+    hasMoreSessions: boolean;
+    /** Base route of the journey page, as passed to the provider. */
+    sessionPageUrl: string;
+    isLoading: boolean;
+    error: string | null;
+}
+type AnalyticsAdminProviderProps = {
+    children: ReactNode;
+    /** ISO 8601 instant. Defaults to 30 days ago. */
+    initialFrom?: string;
+    /** ISO 8601 instant. Defaults to now. */
+    initialTo?: string;
+    /** Route the breadcrumb links back to. */
+    pageUrl?: string;
+    /** Base route of the journey page each session row links to. */
+    sessionPageUrl?: string;
+};
+/**
+ * Owns every filter the administrative analytics page reads, fetches the panels
+ * behind it, and publishes the filter bar into the page title bar.
+ *
+ * The filter bar is rendered into `title.functions` here — NOT in the container —
+ * because `RoundPageContainer`'s title bar reads `title.functions` from
+ * `SharedContext`, and a descendant cannot inject nodes into an ancestor's
+ * provider value. That is why the filter state lives at this level.
+ */
+declare const AnalyticsAdminProvider: ({ children, initialFrom, initialTo, pageUrl, sessionPageUrl, }: AnalyticsAdminProviderProps) => React.JSX.Element;
+declare const useAnalyticsAdmin: () => AnalyticsAdminContextType;
+
+/**
+ * Page body for the administrative analytics dashboard.
+ *
+ * Stateless by design — every value it renders comes from
+ * `useAnalyticsAdmin()`. The filter bar is deliberately NOT here: it belongs to
+ * the page title bar, which `RoundPageContainer` fills from `SharedContext`, so
+ * the provider publishes it (see AnalyticsAdminContext).
+ */
+declare function AnalyticsAdminContainer(): React.JSX.Element;
+
+type FilterState = {
+    from: string;
+    to: string;
+    section: AnalyticsSection;
+    granularity: AnalyticsGranularity;
+};
+type Props$6 = FilterState & {
+    /** Receives ONLY the keys that changed. */
+    onChange: (next: Partial<FilterState>) => void;
+};
+/**
+ * The single control row above the KPI tiles.
+ *
+ * It is deliberately stateless: every control reports the one key it changed and
+ * the owning context re-fetches. Keeping the whole filter state in one place is
+ * what lets the page issue a single coordinated batch of requests instead of one
+ * per control.
+ */
+declare function AnalyticsAdminFilterBar({ section, granularity, onChange }: Props$6): React.JSX.Element;
+
+type Props$5 = {
+    /** The six summary rows: {public, app, total} × {current, previous}. */
+    summary: AnalyticsSummaryInterface[];
+};
+/**
+ * The KPI header of the administrative analytics page.
+ *
+ * Three lead tiles carry the traffic volumes — visitors, sessions, page views —
+ * each with its delta against the equal-length preceding window. Two supporting
+ * tiles below carry the ratios that give those numbers context.
+ *
+ * The tiles read the `total` row: the backend already applies the section filter
+ * to it, so it is the figure for whatever the filter bar selected. The backend
+ * always returns both windows, which is why no tile has to branch on a missing
+ * row: an absent one is simply zero-filled here.
+ */
+declare function AnalyticsAdminTiles({ summary }: Props$5): React.JSX.Element;
+
+type AnalyticsTimelineChartProps = {
+    rows: AnalyticsTimelineInterface[];
+    className?: string;
+};
+/**
+ * Traffic over time as a grouped bar chart: visitors and page views per bucket.
+ *
+ * The backend returns one row per bucket per section; the chart sums the
+ * sections into one entry per bucket. The two series measure different things,
+ * so they sit side by side rather than stacked.
+ *
+ * Colour does an IDENTITY job here — each bar is a series, not a magnitude — so
+ * it draws the fixed categorical order from the token-usage palette (slots 0 and
+ * 1). The palette's light-mode validator run carries a sub-3:1 contrast WARN,
+ * which obliges a relief channel: the legend and the value-carrying tooltip
+ * below are what make the fills readable.
+ */
+declare function AnalyticsTimelineChart({ rows, className }: AnalyticsTimelineChartProps): React.JSX.Element;
+
+type Props$4 = {
+    breakdowns: Record<AnalyticsDimension, AnalyticsBreakdownInterface[]>;
+};
+/**
+ * Attribution and content breakdowns, one tab per dimension.
+ *
+ * Each tab is the same four-column table — key, visitors, sessions, page views —
+ * sorted by visitors. Sorting is client-side because the whole ranked set is
+ * already in memory, so a round trip would buy nothing. Keys are data, not
+ * vocabulary: `(none)` and the routes are rendered as the backend wrote them;
+ * only the `other` rollup is translated.
+ */
+declare function AnalyticsBreakdownTable({ breakdowns }: Props$4): React.JSX.Element;
+
+type Props$3 = {
+    rows: AnalyticsSessionInterface[];
+    /** Base route of the journey page; each row links to `${sessionPageUrl}/${id}`. */
+    sessionPageUrl: string;
+    onLoadMore: () => void;
+    hasMore: boolean;
+};
+/**
+ * The sessions in the selected window, newest first as the backend returns them.
+ *
+ * Paginated by cursor: the owning context holds the next-page reference and
+ * appends on `onLoadMore`, so this table stays stateless. A session linked to a
+ * signed-in user shows the user; any other shows a short visitor suffix, enough
+ * to tell two anonymous visitors apart without displaying the whole id.
+ */
+declare function AnalyticsSessionsTable({ rows, sessionPageUrl, onLoadMore, hasMore }: Props$3): React.JSX.Element;
+
+type Props$2 = {
+    sessionId: string;
+    /** Route of the dashboard; the journey pages live under `${pageUrl}/sessions`. */
+    pageUrl?: string;
+};
+/**
+ * One session, followed page by page.
+ *
+ * The attribution header says where the visitor came from, the page-view table
+ * replays the session in order with the time spent before each step, and the
+ * visitor's other sessions close the page. Unlike the dashboard this page has no
+ * filters, so it fetches on mount without a provider and publishes its own
+ * breadcrumb back to the dashboard.
+ */
+declare function AnalyticsJourneyContainer({ sessionId, pageUrl }: Props$2): React.JSX.Element;
+
+type Props$1 = {
+    /** Route the breadcrumb links back to. Defaults to the provider's default. */
+    pageUrl?: string;
+    /** Base route of the journey page each session row links to. */
+    sessionPageUrl?: string;
+};
+/**
+ * The whole administrative analytics page as one client component, so a host
+ * app's server page renders a single element. `AnalyticsAdminContainer` owns
+ * the `RoundPageContainer`; the provider sits above it because it publishes the
+ * filter bar into the title bar.
+ */
+declare function AnalyticsAdminPageContainer({ pageUrl, sessionPageUrl }: Props$1): React.JSX.Element;
+
+type Props = {
+    sessionId: string;
+    /** Route the breadcrumb links back to. Defaults to the container's default. */
+    pageUrl?: string;
+};
+/** The single-session journey page as one client component. */
+declare function AnalyticsJourneyPageContainer({ sessionId, pageUrl }: Props): React.JSX.Element;
+
+/** Write-only resource: the tracker posts it, rehydrate reads the two attributes back. */
+interface AnalyticsEventInterface extends ApiDataInterface {
+    get path(): string;
+    get section(): string;
+}
+
+/**
+ * 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.
+ */
+declare class AnalyticsEvent extends AbstractApiData implements AnalyticsEventInterface {
+    private _path;
+    private _section;
+    get path(): string;
+    get section(): string;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: AnalyticsEventInput): any;
+}
+
+/** One (section, window) row of the headline tiles: current or previous period. */
+declare class AnalyticsSummary extends AbstractApiData implements AnalyticsSummaryInterface {
+    private _section;
+    private _window;
+    private _visitors;
+    private _sessions;
+    private _pageViews;
+    private _pagesPerSession;
+    private _consentShare;
+    get section(): string;
+    get window(): string;
+    get visitors(): number;
+    get sessions(): number;
+    get pageViews(): number;
+    get pagesPerSession(): number;
+    get consentShare(): number;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: AnalyticsSummaryInput): any;
+}
+
+/** One (bucket, section) point of the visitors-over-time chart. */
+declare class AnalyticsTimeline extends AbstractApiData implements AnalyticsTimelineInterface {
+    private _bucket;
+    private _section;
+    private _visitors;
+    private _sessions;
+    private _pageViews;
+    get bucket(): Date;
+    get section(): string;
+    get visitors(): number;
+    get sessions(): number;
+    get pageViews(): number;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: AnalyticsTimelineInput): any;
+}
+
+/** One row of a breakdown table: a key (source, route, …) and its counts. */
+declare class AnalyticsBreakdown extends AbstractApiData implements AnalyticsBreakdownInterface {
+    private _dimension;
+    private _key;
+    private _visitors;
+    private _sessions;
+    private _pageViews;
+    get dimension(): string;
+    get key(): string;
+    get visitors(): number;
+    get sessions(): number;
+    get pageViews(): number;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: AnalyticsBreakdownInput): any;
+}
+
+/** One visit: a run of page views from one visitor with no 30-minute gap. */
+declare class AnalyticsSession extends AbstractApiData implements AnalyticsSessionInterface {
+    private _visitorId;
+    private _consented;
+    private _startedAt;
+    private _lastSeenAt;
+    private _pageViews;
+    private _section;
+    private _landingRoute;
+    private _referrerHost?;
+    private _utmSource?;
+    private _utmMedium?;
+    private _utmCampaign?;
+    private _utmTerm?;
+    private _utmContent?;
+    private _deviceType;
+    private _user?;
+    get visitorId(): string;
+    get consented(): boolean;
+    get startedAt(): Date;
+    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;
+    get user(): UserInterface | undefined;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: AnalyticsSessionInput): any;
+}
+
+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;
+}
+
+/** One step of a session journey. */
+declare class AnalyticsPageView extends AbstractApiData implements AnalyticsPageViewInterface {
+    private _path;
+    private _route;
+    private _section;
+    get path(): string;
+    get route(): string;
+    get section(): string;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: AnalyticsPageViewInput): any;
+}
+
+declare class AnalyticsService extends AbstractService {
+    /**
+     * Posts one page view. Fire-and-forget: a lost page view must never surface
+     * an error to the visitor, so the global handler is suppressed and any
+     * rejection is logged at debug level and swallowed here.
+     */
+    static track(input: AnalyticsEventInput): Promise<void>;
+}
+
+declare class AnalyticsAdminService extends AbstractService {
+    /** Headline tiles: one row per window (current, previous). */
+    static getSummary(filters: AnalyticsFilters): Promise<AnalyticsSummaryInterface[]>;
+    static getTimeline(params: AnalyticsFilters & {
+        granularity: AnalyticsGranularity;
+    }): Promise<AnalyticsTimelineInterface[]>;
+    static getBreakdown(params: AnalyticsFilters & {
+        dimension: AnalyticsDimension;
+        limit?: number;
+    }): Promise<AnalyticsBreakdownInterface[]>;
+    /** Newest sessions first, cursor-paginated through `next`. */
+    static getSessions(params: AnalyticsFilters & {
+        visitorId?: string;
+        userId?: string;
+        next?: NextRef;
+    }): Promise<AnalyticsSessionInterface[]>;
+    static getSession(params: {
+        id: string;
+    }): Promise<AnalyticsSessionInterface>;
+    /** The journey: every page view of one session, oldest first. */
+    static getSessionPageViews(params: {
+        sessionId: string;
+    }): Promise<AnalyticsPageViewInterface[]>;
+}
+
+/**
+ * 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.
+ */
+declare const ANALYTICS_ADMIN_I18N_KEYS: readonly ["analytics.admin.title", "analytics.admin.description", "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", "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", "analytics.admin.panels.over_time", "analytics.admin.panels.breakdown", "analytics.admin.panels.sessions", "analytics.admin.panels.journey", "analytics.admin.panels.other_sessions", "analytics.admin.dimensions.source", "analytics.admin.dimensions.medium", "analytics.admin.dimensions.campaign", "analytics.admin.dimensions.referrer", "analytics.admin.dimensions.route", "analytics.admin.dimensions.landing", "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", "analytics.admin.anonymous", "analytics.admin.consented", "analytics.admin.not_consented", "analytics.admin.load_more", "analytics.admin.no_data", "analytics.admin.other", "analytics.admin.series.visitors", "analytics.admin.series.page_views"];
+
+export { ANALYTICS_ADMIN_I18N_KEYS, ANALYTICS_DIMENSIONS, ANALYTICS_GRANULARITIES, ANALYTICS_SECTIONS, AnalyticsAdminContainer, type AnalyticsAdminContextType, AnalyticsAdminFilterBar, type AnalyticsAdminFilterState, AnalyticsAdminPageContainer, AnalyticsAdminProvider, AnalyticsAdminService, AnalyticsAdminTiles, AnalyticsBreakdown, type AnalyticsBreakdownInput, type AnalyticsBreakdownInterface, AnalyticsBreakdownTable, type AnalyticsDimension, AnalyticsEvent, type AnalyticsEventInput, type AnalyticsEventInterface, type AnalyticsFilters, type AnalyticsGranularity, AnalyticsJourneyContainer, AnalyticsJourneyPageContainer, AnalyticsPageView, type AnalyticsPageViewInput, type AnalyticsPageViewInterface, type AnalyticsSection, AnalyticsService, AnalyticsSession, type AnalyticsSessionInput, type AnalyticsSessionInterface, AnalyticsSessionsTable, AnalyticsSummary, type AnalyticsSummaryInput, type AnalyticsSummaryInterface, AnalyticsTimeline, AnalyticsTimelineChart, type AnalyticsTimelineInput, type AnalyticsTimelineInterface, AnalyticsTracker, useAnalyticsAdmin };