@byline/host-tanstack-start 6.0.0 → 6.0.2

package/dist/routes/create-admin-analytics-route.js

@@ -6,7 +6,7 @@ import { useTranslation } from "@byline/i18n/react";
 import { z } from "zod";
 import { BreadcrumbsClient } from "../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js";
 import { useNavigate } from "../admin-shell/chrome/loose-router.js";
-import { getAnalyticsCountries, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop } from "../server-fns/analytics/index.js";
+import { getAnalyticsCountries, getAnalyticsDashboardPreference, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop, setAnalyticsDashboardPreference } from "../server-fns/analytics/index.js";
 import { getAdminRoutePath } from "./admin-path.js";
 import { buildAnalyticsDashboardRange } from "./analytics-range.js";
 const periodSchema = z.preprocess((value)=>{
@@ -21,13 +21,19 @@ function createAdminAnalyticsRoute(path) {
     const Route = createFileRoute(path)({
         validateSearch: searchSchema,
         loaderDeps: ({ search })=>({
-                period: search.period ?? 30
+                period: search.period
             }),
         loader: async ({ deps })=>{
             const runtime = await getAnalyticsRuntime();
             if (!runtime.enabled) throw notFound();
-            const coverage = await getAnalyticsReportCoverage();
-            const range = buildAnalyticsDashboardRange(deps.period, new Date(), coverage.summaryFrom);
+            const [coverage, preference] = await Promise.all([
+                getAnalyticsReportCoverage(),
+                null == deps.period ? getAnalyticsDashboardPreference() : Promise.resolve({
+                    period: null
+                })
+            ]);
+            const period = deps.period ?? preference.period ?? 30;
+            const range = buildAnalyticsDashboardRange(period, new Date(), coverage.summaryFrom);
             const [summary, pages, downloads, referrers, countries] = await Promise.all([
                 getAnalyticsSummary({
                     data: range
@@ -66,7 +72,7 @@ function createAdminAnalyticsRoute(path) {
                     range,
                     coverage
                 },
-                period: deps.period
+                period
             };
         },
         component: function() {
@@ -109,6 +115,13 @@ function createAdminAnalyticsRoute(path) {
                                     period: nextPeriod
                                 }
                             });
+                            setAnalyticsDashboardPreference({
+                                data: {
+                                    period: nextPeriod
+                                }
+                            }).catch((err)=>{
+                                console.warn('analytics dashboard preference save failed:', err);
+                            });
                         }
                     })
                 ]

package/dist/server-fns/analytics/index.d.ts

@@ -6,4 +6,5 @@
  * Copyright (c) Infonomic Company Limited
  */
 export { type DeleteAnalyticsEventsInput, deleteAnalyticsEvents, rebuildAnalyticsDay, } from './maintenance.js';
+export { getAnalyticsDashboardPreference, setAnalyticsDashboardPreference, } from './preferences.js';
 export { type AnalyticsRuntimeState, type AnalyticsTopInput, getAnalyticsCountries, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop, } from './queries.js';

package/dist/server-fns/analytics/index.js

@@ -1,2 +1,3 @@
 export { deleteAnalyticsEvents, rebuildAnalyticsDay } from "./maintenance.js";
+export { getAnalyticsDashboardPreference, setAnalyticsDashboardPreference } from "./preferences.js";
 export { getAnalyticsCountries, getAnalyticsReferrers, getAnalyticsReportCoverage, getAnalyticsRuntime, getAnalyticsSummary, getAnalyticsTop } from "./queries.js";

package/dist/server-fns/analytics/preferences.d.ts

@@ -0,0 +1,36 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { AnalyticsDashboardPeriod } from '@byline/admin/analytics';
+export interface SetAnalyticsDashboardPreferenceInput {
+    period: AnalyticsDashboardPeriod;
+}
+/**
+ * The stored period, or `null` when the user has never chosen one (or
+ * this host has no admin store).
+ *
+ * Never throws: a preference read must not be able to take the
+ * dashboard down. A headless context, an unauthenticated preview, or a
+ * database hiccup logs and yields `null`, and the caller falls back to
+ * the built-in default — the same posture the collection list's
+ * preference read takes.
+ */
+export declare const getAnalyticsDashboardPreference: import("@tanstack/react-start").OptionalFetcher<readonly [import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, undefined, {
+    bylineExpectedSessionId: string | null;
+}, undefined, undefined>], undefined, Promise<{
+    period: AnalyticsDashboardPeriod | null;
+}>>;
+/**
+ * Persist the chosen period. Fire-and-forget from the dashboard: the
+ * navigation has already happened, so a failed save must never toast,
+ * block, or roll anything back.
+ */
+export declare const setAnalyticsDashboardPreference: import("@tanstack/react-start").RequiredFetcher<readonly [import("@tanstack/react-start").FunctionMiddlewareAfterServer<{}, unknown, undefined, undefined, {
+    bylineExpectedSessionId: string | null;
+}, undefined, undefined>], (input: SetAnalyticsDashboardPreferenceInput) => SetAnalyticsDashboardPreferenceInput, Promise<{
+    ok: true;
+}>>;

package/dist/server-fns/analytics/preferences.js

@@ -0,0 +1,60 @@
+import { createServerFn } from "@tanstack/react-start";
+import { getPreferenceCommand, setPreferenceCommand } from "@byline/admin/admin-preferences";
+import { isAnalyticsDashboardPeriod } from "@byline/analytics/config";
+import { getAdminRequestContext } from "@byline/client/server";
+import { getLogger } from "@byline/core";
+import { bylineCore } from "../../integrations/byline-core.js";
+import { adminSessionMiddleware } from "../../integrations/session-middleware.js";
+const ANALYTICS_DASHBOARD_SCOPE = 'analytics.dashboard';
+const getAnalyticsDashboardPreference = createServerFn({
+    method: 'GET'
+}).middleware([
+    adminSessionMiddleware
+]).handler(async ()=>{
+    const adminStore = bylineCore().adminStore;
+    if (null == adminStore) return {
+        period: null
+    };
+    try {
+        const context = await getAdminRequestContext();
+        const result = await getPreferenceCommand(context, {
+            scope: ANALYTICS_DASHBOARD_SCOPE
+        }, {
+            store: adminStore
+        });
+        const period = result.value?.period;
+        return {
+            period: isAnalyticsDashboardPeriod(period) ? period : null
+        };
+    } catch (err) {
+        getLogger().warn({
+            err
+        }, 'analytics dashboard preference read failed — using default');
+        return {
+            period: null
+        };
+    }
+});
+const setAnalyticsDashboardPreference = createServerFn({
+    method: 'POST'
+}).middleware([
+    adminSessionMiddleware
+]).validator((input)=>input).handler(async ({ data })=>{
+    const adminStore = bylineCore().adminStore;
+    if (null == adminStore) return {
+        ok: true
+    };
+    const context = await getAdminRequestContext();
+    await setPreferenceCommand(context, {
+        scope: ANALYTICS_DASHBOARD_SCOPE,
+        value: {
+            period: data.period
+        }
+    }, {
+        store: adminStore
+    });
+    return {
+        ok: true
+    };
+});
+export { getAnalyticsDashboardPreference, setAnalyticsDashboardPreference };

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -125,15 +125,15 @@
     "react-json-view-lite": "^2.5.0",
     "react-swipeable": "^7.0.2",
     "zod": "^4.6.2",
-    "@byline/admin": "6.0.0",
-    "@byline/ai": "6.0.0",
-    "@byline/analytics": "6.0.0",
-    "@byline/analytics-agent": "6.0.0",
-    "@byline/core": "6.0.0",
-    "@byline/client": "6.0.0",
-    "@byline/i18n": "6.0.0",
-    "@byline/ui": "6.0.0",
-    "@byline/auth": "6.0.0"
+    "@byline/admin": "6.0.2",
+    "@byline/auth": "6.0.2",
+    "@byline/analytics": "6.0.2",
+    "@byline/analytics-agent": "6.0.2",
+    "@byline/client": "6.0.2",
+    "@byline/ai": "6.0.2",
+    "@byline/i18n": "6.0.2",
+    "@byline/core": "6.0.2",
+    "@byline/ui": "6.0.2"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",

package/src/routes/create-admin-analytics-route.tsx

@@ -21,11 +21,13 @@ import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs
 import { useNavigate } from '../admin-shell/chrome/loose-router.js'
 import {
   getAnalyticsCountries,
+  getAnalyticsDashboardPreference,
   getAnalyticsReferrers,
   getAnalyticsReportCoverage,
   getAnalyticsRuntime,
   getAnalyticsSummary,
   getAnalyticsTop,
+  setAnalyticsDashboardPreference,
 } from '../server-fns/analytics/index.js'
 import { getAdminRoutePath } from './admin-path.js'
 import { buildAnalyticsDashboardRange } from './analytics-range.js'
@@ -47,15 +49,29 @@ interface AnalyticsSearch {
 export function createAdminAnalyticsRoute(path: string) {
   const Route: any = createFileRoute(path as never)({
     validateSearch: searchSchema,
+    // `period` stays possibly-undefined here rather than defaulting to 30:
+    // "no period in the URL" is a distinct state from "30 in the URL", and
+    // only the former defers to the user's stored preference. It is still a
+    // loader dep, so an explicit period change refetches.
     loaderDeps: ({ search }: { search: AnalyticsSearch }) => ({
-      period: search.period ?? 30,
+      period: search.period,
     }),
-    loader: async ({ deps }: { deps: { period: AnalyticsDashboardPeriod } }) => {
+    loader: async ({ deps }: { deps: { period?: AnalyticsDashboardPeriod } }) => {
       const runtime = await getAnalyticsRuntime()
       if (!runtime.enabled) throw notFound()
 
-      const coverage = await getAnalyticsReportCoverage()
-      const range = buildAnalyticsDashboardRange(deps.period, new Date(), coverage.summaryFrom)
+      // Both are roundtrips the dashboard has to make before it can build a
+      // range, so the preference read rides along in parallel and costs no
+      // added latency. It is skipped entirely when the URL already decides.
+      const [coverage, preference] = await Promise.all([
+        getAnalyticsReportCoverage(),
+        deps.period == null ? getAnalyticsDashboardPreference() : Promise.resolve({ period: null }),
+      ])
+
+      // Precedence, matching the collection list: explicit URL param →
+      // stored per-user preference → the built-in default.
+      const period: AnalyticsDashboardPeriod = deps.period ?? preference.period ?? 30
+      const range = buildAnalyticsDashboardRange(period, new Date(), coverage.summaryFrom)
       const [summary, pages, downloads, referrers, countries] = await Promise.all([
         getAnalyticsSummary({ data: range }),
         // Fetch exactly the preview depth each card shows; the full list is
@@ -76,7 +92,9 @@ export function createAdminAnalyticsRoute(path: string) {
           range,
           coverage,
         } satisfies AnalyticsDashboardData,
-        period: deps.period,
+        // The *effective* period, so a params-less landing still highlights
+        // the period that actually ordered the data.
+        period,
       }
     },
     component: function AdminAnalyticsComponent() {
@@ -116,6 +134,14 @@ export function createAdminAnalyticsRoute(path: string) {
                 to: getAdminRoutePath('analytics'),
                 search: { period: nextPeriod },
               })
+              // Quietly make the choice sticky for next session. Fire-and-
+              // forget: the navigation already happened, so a failed save
+              // must never toast, block, or roll anything back.
+              setAnalyticsDashboardPreference({ data: { period: nextPeriod } }).catch(
+                (err: unknown) => {
+                  console.warn('analytics dashboard preference save failed:', err)
+                }
+              )
             }}
           />
         </>

package/src/server-fns/analytics/index.ts

@@ -11,6 +11,10 @@ export {
   deleteAnalyticsEvents,
   rebuildAnalyticsDay,
 } from './maintenance.js'
+export {
+  getAnalyticsDashboardPreference,
+  setAnalyticsDashboardPreference,
+} from './preferences.js'
 export {
   type AnalyticsRuntimeState,
   type AnalyticsTopInput,

package/src/server-fns/analytics/preferences.ts

@@ -0,0 +1,99 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Read and persist the signed-in admin user's sticky analytics
+ * dashboard period.
+ *
+ * The dashboard keeps its period in the URL (`?period=90`), so a shared
+ * link still opens exactly as sent; this preference only supplies the
+ * period when the URL carries none. Same precedence the collection list
+ * uses for page size and sort — explicit params win, the stored
+ * preference fills in, the built-in default is last.
+ *
+ * The scope is a singleton (`analytics.dashboard`), unlike the
+ * collection list's per-path scopes, so there is nothing to validate
+ * the way `set-list-view-preference` validates a collection path.
+ *
+ * Self-service: the target user is always the authenticated actor.
+ */
+
+import { createServerFn } from '@tanstack/react-start'
+
+import { getPreferenceCommand, setPreferenceCommand } from '@byline/admin/admin-preferences'
+import type { AnalyticsDashboardPeriod } from '@byline/admin/analytics'
+import { isAnalyticsDashboardPeriod } from '@byline/analytics/config'
+import { getAdminRequestContext } from '@byline/client/server'
+import { getLogger } from '@byline/core'
+
+import { bylineCore } from '../../integrations/byline-core.js'
+import { adminSessionMiddleware } from '../../integrations/session-middleware.js'
+
+const ANALYTICS_DASHBOARD_SCOPE = 'analytics.dashboard'
+
+export interface SetAnalyticsDashboardPreferenceInput {
+  period: AnalyticsDashboardPeriod
+}
+
+/**
+ * The stored period, or `null` when the user has never chosen one (or
+ * this host has no admin store).
+ *
+ * Never throws: a preference read must not be able to take the
+ * dashboard down. A headless context, an unauthenticated preview, or a
+ * database hiccup logs and yields `null`, and the caller falls back to
+ * the built-in default — the same posture the collection list's
+ * preference read takes.
+ */
+export const getAnalyticsDashboardPreference = createServerFn({ method: 'GET' })
+  .middleware([adminSessionMiddleware])
+  .handler(async (): Promise<{ period: AnalyticsDashboardPeriod | null }> => {
+    const adminStore = bylineCore().adminStore
+    if (adminStore == null) return { period: null }
+
+    try {
+      const context = await getAdminRequestContext()
+      const result = await getPreferenceCommand(
+        context,
+        { scope: ANALYTICS_DASHBOARD_SCOPE },
+        { store: adminStore }
+      )
+      const period = (result.value as { period?: unknown } | null)?.period
+      // Re-validated on the way out, not just on the way in: a row
+      // written before a period was retired from the dashboard must
+      // degrade to the default rather than reach `buildAnalyticsDashboardRange`.
+      return { period: isAnalyticsDashboardPeriod(period) ? period : null }
+    } catch (err) {
+      getLogger().warn({ err }, 'analytics dashboard preference read failed — using default')
+      return { period: null }
+    }
+  })
+
+/**
+ * Persist the chosen period. Fire-and-forget from the dashboard: the
+ * navigation has already happened, so a failed save must never toast,
+ * block, or roll anything back.
+ */
+export const setAnalyticsDashboardPreference = createServerFn({ method: 'POST' })
+  .middleware([adminSessionMiddleware])
+  .validator((input: SetAnalyticsDashboardPreferenceInput) => input)
+  .handler(async ({ data }) => {
+    const adminStore = bylineCore().adminStore
+    if (adminStore == null) {
+      // Headless hosts without an admin store have no preference storage —
+      // the save is a silent no-op, mirroring set-locale's posture.
+      return { ok: true as const }
+    }
+    const context = await getAdminRequestContext()
+    await setPreferenceCommand(
+      context,
+      { scope: ANALYTICS_DASHBOARD_SCOPE, value: { period: data.period } },
+      { store: adminStore }
+    )
+    return { ok: true as const }
+  })