@canonry/canonry 4.139.1 → 4.142.0

package/dist/{chunk-DJHSOPMU.js → chunk-NR6OGEV3.js}

@@ -240,11 +240,13 @@ import {
   gscDeindexedRowSchema,
   gscDiscoverSitemapsResponseDtoSchema,
   gscPerformanceDailyDtoSchema,
-  gscSearchDataDtoSchema,
+  gscPerformanceOrderBySchema,
+  gscPerformanceResponseDtoSchema,
   gscSiteListResponseDtoSchema,
   gscSitemapListResponseDtoSchema,
   gscSubmitSitemapsRequestDtoSchema,
   gscSubmitSitemapsResponseDtoSchema,
+  gscTopPagesDtoSchema,
   gscUrlInspectionDtoSchema,
   hasLocationLabel,
   healthSnapshotDtoSchema,
@@ -280,6 +282,7 @@ import {
   orderLocationsDefaultFirst,
   organicEvidenceDtoSchema,
   organicEvidencePeriodSchema,
+  parseBoundedRate,
   parseInclusiveEndMs,
   parseReportPeriodDays,
   parseRunError,
@@ -309,6 +312,7 @@ import {
   researchRunDetailSchema,
   researchRunListSchema,
   resolveConfigSpecQueries,
+  resolveDateRange,
   resolveLocations,
   resolveSnapshotRequestQueries,
   resultsExportDtoSchema,
@@ -378,7 +382,7 @@ import {
   wordpressSchemaDeployResultDtoSchema,
   wordpressSchemaStatusResultDtoSchema,
   wordpressStatusDtoSchema
-} from "./chunk-OA2EGCUS.js";
+} from "./chunk-LS6SEZVF.js";
 
 // src/intelligence-service.ts
 import { eq as eq45, desc as desc22, asc as asc9, and as and36, ne as ne6, or as or10, inArray as inArray15, gte as gte12, lte as lte8 } from "drizzle-orm";
@@ -949,6 +953,23 @@ var gaDailyTotals = sqliteTable("ga_daily_totals", {
   date: text("date").notNull(),
   sessions: integer("sessions").notNull().default(0),
   users: integer("users").notNull().default(0),
+  /**
+   * GA4's `engagementRate` for the day (0-1), requested directly from the Data
+   * API. Nullable, with no default: every row written before the metric was
+   * added has no reading, and defaulting to 0 would report a real "nobody
+   * engaged" day for the whole pre-migration period.
+   */
+  engagementRate: real("engagement_rate"),
+  /**
+   * GA4's `newUsers` for the day. Nullable: rows written before this column
+   * existed have no reading, and a 0 would read as a real "no new users" day.
+   *
+   * Stored on its own merit. It is NOT an input to a returning-users figure:
+   * a visitor can be first-seen and return inside the same range, so
+   * `users - newUsers` does not reconstruct one. That needs the
+   * `newVsReturning` dimension.
+   */
+  newUsers: integer("new_users"),
   syncedAt: text("synced_at").notNull(),
   syncRunId: text("sync_run_id").references(() => runs.id, { onDelete: "cascade" }),
   createdAt: text("created_at").notNull()
@@ -4441,6 +4462,25 @@ var MIGRATION_VERSIONS = [
          ON query_basket_versions(project_id, checksum)`,
       `ALTER TABLE runs ADD COLUMN query_basket_revision INTEGER`
     ]
+  },
+  {
+    // GA4 engagement metrics on the property-level daily series.
+    //
+    // `engagement_rate` and `new_users` are both real GA4 metrics, requested
+    // directly. No returning-users column: GA4 exposes no such metric, and
+    // `users - new_users` does not reconstruct one because a visitor can be
+    // first-seen AND return inside the same range. That needs the
+    // `newVsReturning` dimension, which changes the row shape of the sync.
+    //
+    // Both columns are NULLABLE with no default. Every row written before this
+    // migration has no reading, and NOT NULL DEFAULT 0 would turn that absence
+    // into a real "0% engaged" day.
+    version: 116,
+    name: "ga-daily-totals-engagement",
+    statements: [
+      `ALTER TABLE ga_daily_totals ADD COLUMN engagement_rate REAL`,
+      `ALTER TABLE ga_daily_totals ADD COLUMN new_users INTEGER`
+    ]
   }
 ];
 function rebuildBacklinkTableWithSource(tx, table) {
@@ -15178,6 +15218,31 @@ function clickPeriods(periods, clicks, impressions) {
     impressions: impressions[index2] ?? 0
   }));
 }
+function engagementPeriods(periods, rows) {
+  return periods.map((period2) => {
+    const inPeriod = rows.filter((row) => row.date >= period2.startDate && row.date <= period2.endDate);
+    const rateDays = inPeriod.filter((row) => row.engagementRate !== null);
+    const weight = rateDays.reduce((sum, row) => sum + row.sessions, 0);
+    const weighted = rateDays.reduce((sum, row) => sum + row.engagementRate * row.sessions, 0);
+    const splitDays = inPeriod.filter((row) => row.newUsers !== null);
+    const dailyTotalUsers = splitDays.reduce((sum, row) => sum + row.users, 0);
+    const dailyNewUsers = splitDays.reduce((sum, row) => sum + row.newUsers, 0);
+    return {
+      ...period2,
+      sessions: inPeriod.reduce((sum, row) => sum + row.sessions, 0),
+      // A bucket whose reading-days had no sessions has no rate to report; the
+      // weighted mean would be 0/0.
+      engagementRate: rateDays.length > 0 && weight > 0 ? weighted / weight : null,
+      dailyTotalUsers: splitDays.length > 0 ? dailyTotalUsers : null,
+      dailyNewUsers: splitDays.length > 0 ? dailyNewUsers : null,
+      // Null on a zero denominator too: a share of no users is not 0%.
+      metricsAvailable: rateDays.length > 0 || splitDays.length > 0,
+      daysInPeriod: inPeriod.length,
+      daysWithEngagementRate: rateDays.length,
+      daysWithUserSplit: splitDays.length
+    };
+  });
+}
 function rankEntries(entries) {
   const score = (values) => ({
     latest: values.at(-1) ?? 0,
@@ -15299,6 +15364,23 @@ function buildGaMeasurementAnalysis(db, projectName, options = {}) {
   const gaStartDate = gaPeriods[0]?.startDate;
   const acquisitionRows = gaStartDate ? db.select().from(gaAcquisitionDaily).where(and14(eq18(gaAcquisitionDaily.projectId, project.id), gte5(gaAcquisitionDaily.date, gaStartDate), lte2(gaAcquisitionDaily.date, gaAnchor))).all() : [];
   const leadRows = gaStartDate ? db.select().from(gaLeadEventsDaily).where(and14(eq18(gaLeadEventsDaily.projectId, project.id), gte5(gaLeadEventsDaily.date, gaStartDate), lte2(gaLeadEventsDaily.date, gaAnchor))).all() : [];
+  const engagementAnchor = db.select({ date: sql9`max(${gaDailyTotals.date})` }).from(gaDailyTotals).where(eq18(gaDailyTotals.projectId, project.id)).get()?.date ?? null;
+  const engagementPeriodWindow = engagementAnchor ? buildPeriods(engagementAnchor, days) : [];
+  const engagementStartDate = engagementPeriodWindow[0]?.startDate;
+  const engagementRows = engagementStartDate ? db.select().from(gaDailyTotals).where(and14(
+    eq18(gaDailyTotals.projectId, project.id),
+    gte5(gaDailyTotals.date, engagementStartDate),
+    lte2(gaDailyTotals.date, engagementAnchor)
+  )).all() : [];
+  const engagementAvailableFrom = db.select({
+    date: sql9`min(${gaDailyTotals.date})`
+  }).from(gaDailyTotals).where(and14(
+    eq18(gaDailyTotals.projectId, project.id),
+    or4(
+      sql9`${gaDailyTotals.engagementRate} is not null`,
+      sql9`${gaDailyTotals.newUsers} is not null`
+    )
+  )).get()?.date ?? null;
   const gscAnchor = db.select({ date: sql9`max(${gscDailyTotals.date})` }).from(gscDailyTotals).where(eq18(gscDailyTotals.projectId, project.id)).get()?.date ?? null;
   const gscPeriods = gscAnchor ? buildPeriods(gscAnchor, days) : [];
   const gscStartDate = gscPeriods[0]?.startDate;
@@ -15458,6 +15540,12 @@ function buildGaMeasurementAnalysis(db, projectName, options = {}) {
         periods: eventPeriods(gaPeriods, values)
       }))
     },
+    engagement: {
+      status: engagementAnchor === null ? "unavailable" : "ready",
+      availableFromDate: engagementAvailableFrom,
+      latestDate: engagementAnchor,
+      periods: engagementPeriods(engagementPeriodWindow, engagementRows)
+    },
     searchDemand: gscAnchor === null ? {
       status: "unavailable",
       periods: [],
@@ -17766,7 +17854,8 @@ var SCHEMA_TABLE = {
   GscCoverageSummaryDto: gscCoverageSummaryDtoSchema,
   GscDeindexedRowDto: gscDeindexedRowSchema,
   GscPerformanceDailyDto: gscPerformanceDailyDtoSchema,
-  GscSearchDataDto: gscSearchDataDtoSchema,
+  GscPerformanceResponseDto: gscPerformanceResponseDtoSchema,
+  GscTopPagesDto: gscTopPagesDtoSchema,
   GscDiscoverSitemapsResponseDto: gscDiscoverSitemapsResponseDtoSchema,
   GscSiteListResponseDto: gscSiteListResponseDtoSchema,
   GscSubmitSitemapsResponseDto: gscSubmitSitemapsResponseDtoSchema,
@@ -18105,9 +18194,21 @@ var reportAudienceQueryParameter = {
 var analyticsWindowParameter = {
   name: "window",
   in: "query",
-  description: "Time window for analytics queries.",
+  description: "Time window for analytics queries. An unrecognised value is rejected with 400; it is never widened to the full history.",
   schema: { type: "string", enum: ["7d", "30d", "90d", "all"] }
 };
+var analyticsStartDateParameter = {
+  name: "startDate",
+  in: "query",
+  description: 'Inclusive lower bound as a calendar date (YYYY-MM-DD). Takes precedence over "window", which is rolling from now and cannot name a calendar month.',
+  schema: stringSchema
+};
+var analyticsEndDateParameter = {
+  name: "endDate",
+  in: "query",
+  description: "Inclusive upper bound as a calendar date (YYYY-MM-DD).",
+  schema: stringSchema
+};
 var organicEvidencePeriodQueryParameter = {
   name: "period",
   in: "query",
@@ -19717,15 +19818,22 @@ var routeCatalog = [
       { name: "endDate", in: "query", description: "Filter by end date.", schema: stringSchema },
       { name: "query", in: "query", description: "Filter by search query.", schema: stringSchema },
       { name: "page", in: "query", description: "Filter by page URL.", schema: stringSchema },
+      {
+        name: "orderBy",
+        in: "query",
+        description: "Row ordering, always descending. Defaults to clicks. Use date for time-series reads.",
+        schema: { type: "string", enum: ["clicks", "impressions", "date"] }
+      },
       limitQueryParameter,
       offsetQueryParameter,
       analyticsWindowParameter
     ],
     responses: {
-      // Handler returns an array of GscSearchDataDto rows (web's
-      // ApiGscPerformanceRow[] confirms). Was incorrectly spec'd as a
-      // single object, which silently truncated client types to one row.
-      200: jsonArrayResponse("GSC performance rows returned.", "GscSearchDataDto"),
+      // Envelope, not a bare array: `totalMatching` / `truncated` are how a
+      // caller tells a page from a complete answer, and `latestAvailableDate`
+      // is how it tells "no data" from "asked past the GSC reporting lag".
+      200: jsonResponse("GSC performance page plus match count and data freshness.", "GscPerformanceResponseDto"),
+      400: errorResponse("Invalid orderBy value."),
       404: errorResponse("Project not found.")
     }
   },
@@ -19745,6 +19853,24 @@ var routeCatalog = [
       404: errorResponse("Project not found.")
     }
   },
+  {
+    method: "get",
+    path: "/api/v1/projects/{name}/google/gsc/top-pages",
+    summary: "Get top GSC pages ranked by clicks",
+    description: "One row per page, aggregated in SQL and ranked by summed clicks descending. The rows are a RANKING built from the dimensioned search-data table; `totals` is NOT their sum. Google withholds rare queries (summed clicks under-count) and fans one impression across every query/page/country/device combination (summed impressions over-count), so `totals` is read from the un-dimensioned property-level daily table and labelled `totalsSource: property-daily`. It is null when that table has no rows in the window.",
+    tags: ["google"],
+    parameters: [
+      nameParameter,
+      { name: "startDate", in: "query", description: "Filter by start date.", schema: stringSchema },
+      { name: "endDate", in: "query", description: "Filter by end date.", schema: stringSchema },
+      limitQueryParameter,
+      analyticsWindowParameter
+    ],
+    responses: {
+      200: jsonResponse("Ranked pages plus the property-level window total.", "GscTopPagesDto"),
+      404: errorResponse("Project not found.")
+    }
+  },
   {
     method: "post",
     path: "/api/v1/projects/{name}/google/gsc/inspect",
@@ -21536,7 +21662,7 @@ var routeCatalog = [
     path: "/api/v1/projects/{name}/ga/traffic",
     summary: "Get GA4 landing page traffic, channel breakdown, and AI referral landing pages",
     tags: ["ga4"],
-    parameters: [nameParameter, limitQueryParameter, analyticsWindowParameter],
+    parameters: [nameParameter, limitQueryParameter, analyticsWindowParameter, analyticsStartDateParameter, analyticsEndDateParameter],
     responses: {
       // TODO: Add `GaTrafficResponse` Zod schema in contracts.
       200: rawJsonResponse("GA4 traffic data returned.", looseObjectSchema),
@@ -21550,7 +21676,7 @@ var routeCatalog = [
     summary: "Get raw AI referral detail rows per day, landing page, and attribution dimension",
     description: "Detail rows, not totals. One row per landing page per attribution dimension, so a single day of one source is many rows and each is commonly worth one session. Use /ga/ai-referral-daily for per-date or per-source session counts.",
     tags: ["ga4"],
-    parameters: [nameParameter, analyticsWindowParameter],
+    parameters: [nameParameter, analyticsWindowParameter, analyticsStartDateParameter, analyticsEndDateParameter],
     responses: {
       200: jsonArrayResponse("AI referral history returned.", "GA4AiReferralHistoryEntry"),
       400: errorResponse("GA4 is not connected."),
@@ -21563,7 +21689,7 @@ var routeCatalog = [
     summary: "Get AI referral sessions per day and per source",
     description: "Sums landing pages within one attribution dimension and never across dimensions, so totalSessions equals the aiSessionsDeduped reported by /ga/traffic for the same window. Sessions only: GA counts users as a distinct count at the grain requested, so an AI-referral user total cannot be summed from these rows and no un-dimensioned AI-referral fetch exists to supply one.",
     tags: ["ga4"],
-    parameters: [nameParameter, analyticsWindowParameter],
+    parameters: [nameParameter, analyticsWindowParameter, analyticsStartDateParameter, analyticsEndDateParameter],
     responses: {
       200: jsonResponse("AI referral daily series returned.", "GA4AiReferralDailyDto"),
       400: errorResponse("GA4 is not connected."),
@@ -21575,7 +21701,7 @@ var routeCatalog = [
     path: "/api/v1/projects/{name}/ga/social-referral-history",
     summary: "Get social media referral sessions per day grouped by source",
     tags: ["ga4"],
-    parameters: [nameParameter, analyticsWindowParameter],
+    parameters: [nameParameter, analyticsWindowParameter, analyticsStartDateParameter, analyticsEndDateParameter],
     responses: {
       200: jsonArrayResponse("Social referral history returned.", "GA4SocialReferralHistoryEntry"),
       400: errorResponse("GA4 is not connected."),
@@ -21613,7 +21739,7 @@ var routeCatalog = [
     path: "/api/v1/projects/{name}/ga/session-history",
     summary: "Get total sessions per day for the project",
     tags: ["ga4"],
-    parameters: [nameParameter, analyticsWindowParameter],
+    parameters: [nameParameter, analyticsWindowParameter, analyticsStartDateParameter, analyticsEndDateParameter],
     responses: {
       200: jsonArrayResponse("Session history returned.", "GA4SessionHistoryEntry"),
       400: errorResponse("GA4 is not connected."),
@@ -24205,7 +24331,17 @@ var GA4_DIMENSIONS = {
 var GA4_METRICS = {
   sessions: "sessions",
   totalUsers: "totalUsers",
-  eventCount: "eventCount"
+  eventCount: "eventCount",
+  /** Share of sessions that were engaged. A real GA4 metric — request it directly. */
+  engagementRate: "engagementRate",
+  /**
+   * First-time users, a real GA4 metric requested directly.
+   *
+   * Not an input to a returning-users figure: a visitor can be first-seen and
+   * return inside the same range, so subtracting this from totalUsers does not
+   * reconstruct one.
+   */
+  newUsers: "newUsers"
 };
 
 // ../integration-google-analytics/src/types.ts
@@ -24753,6 +24889,15 @@ async function fetchAggregateSummary(accessToken, propertyId, days) {
   ga4Log("info", "fetch-aggregate.done", { propertyId, ...summary });
   return summary;
 }
+function parseOptionalMetric(value) {
+  if (value === void 0 || value.trim() === "") return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function parseOptionalCountMetric(value) {
+  const parsed = parseOptionalMetric(value);
+  return parsed === null ? null : Math.round(parsed);
+}
 async function fetchDailyTotals(accessToken, propertyId, days) {
   validateAccessToken2(accessToken);
   validatePropertyId(propertyId);
@@ -24764,14 +24909,25 @@ async function fetchDailyTotals(accessToken, propertyId, days) {
   const res = await runReport(accessToken, propertyId, {
     dateRanges: [{ startDate: formatDate2(startDate), endDate: formatDate2(endDate) }],
     dimensions: [{ name: GA4_DIMENSIONS.date }],
-    metrics: [{ name: GA4_METRICS.sessions }, { name: GA4_METRICS.totalUsers }],
+    metrics: [
+      { name: GA4_METRICS.sessions },
+      { name: GA4_METRICS.totalUsers },
+      { name: GA4_METRICS.engagementRate },
+      { name: GA4_METRICS.newUsers }
+    ],
     limit: syncDays + 1
   });
-  const rows = (res.rows ?? []).map((row) => ({
-    date: compactDateToIso(row.dimensionValues[0]?.value ?? ""),
-    sessions: parseInt(row.metricValues[0]?.value ?? "0", 10) || 0,
-    users: parseInt(row.metricValues[1]?.value ?? "0", 10) || 0
-  })).filter((row) => row.date.length > 0);
+  const rows = (res.rows ?? []).map((row) => {
+    const users = parseInt(row.metricValues[1]?.value ?? "0", 10) || 0;
+    const newUsers = parseOptionalCountMetric(row.metricValues[3]?.value);
+    return {
+      date: compactDateToIso(row.dimensionValues[0]?.value ?? ""),
+      sessions: parseInt(row.metricValues[0]?.value ?? "0", 10) || 0,
+      users,
+      engagementRate: parseBoundedRate(parseOptionalMetric(row.metricValues[2]?.value)),
+      newUsers
+    };
+  }).filter((row) => row.date.length > 0);
   ga4Log("info", "fetch-daily-totals.done", { propertyId, days: syncDays, rows: rows.length });
   return rows;
 }
@@ -25773,6 +25929,13 @@ async function googleRoutes(app, opts) {
   app.get("/projects/:name/google/gsc/performance", async (request) => {
     const project = resolveProject(app.db, request.params.name);
     const { startDate, endDate, query, page, limit, offset } = request.query;
+    const parsedOrderBy = gscPerformanceOrderBySchema.safeParse(request.query.orderBy ?? "clicks");
+    if (!parsedOrderBy.success) {
+      throw validationError(
+        `orderBy must be one of: ${gscPerformanceOrderBySchema.options.join(", ")}`
+      );
+    }
+    const orderBy = parsedOrderBy.data;
     const cutoffDate = !startDate ? windowCutoff(parseWindow(request.query.window))?.slice(0, 10) ?? null : null;
     const conditions = [eq27(gscSearchData.projectId, project.id)];
     if (startDate) conditions.push(sql12`${gscSearchData.date} >= ${startDate}`);
@@ -25782,18 +25945,34 @@ async function googleRoutes(app, opts) {
     if (page) conditions.push(sql12`${gscSearchData.page} LIKE ${"%" + escapeLikePattern(page) + "%"} ESCAPE '\\'`);
     const limitVal = Math.max(parseInt(limit ?? "500", 10) || 0, 1);
     const offsetVal = Math.max(parseInt(offset ?? "0", 10) || 0, 0);
-    const rows = app.db.select().from(gscSearchData).where(and21(...conditions)).orderBy(desc13(gscSearchData.date)).limit(limitVal).offset(offsetVal).all();
-    return rows.map((r) => ({
-      date: r.date,
-      query: r.query,
-      page: r.page,
-      country: r.country,
-      device: r.device,
-      clicks: r.clicks,
-      impressions: r.impressions,
-      ctr: parseFloat(r.ctr),
-      position: parseFloat(r.position)
-    }));
+    const orderColumns = {
+      clicks: [desc13(gscSearchData.clicks), desc13(gscSearchData.date), gscSearchData.query],
+      impressions: [desc13(gscSearchData.impressions), desc13(gscSearchData.date), gscSearchData.query],
+      date: [desc13(gscSearchData.date), desc13(gscSearchData.clicks), gscSearchData.query]
+    }[orderBy];
+    const rows = app.db.select().from(gscSearchData).where(and21(...conditions)).orderBy(...orderColumns).limit(limitVal).offset(offsetVal).all();
+    const totalMatching = app.db.select({ total: sql12`COUNT(*)` }).from(gscSearchData).where(and21(...conditions)).get()?.total ?? 0;
+    const latestAvailableDate = app.db.select({ latest: sql12`MAX(${gscSearchData.date})` }).from(gscSearchData).where(eq27(gscSearchData.projectId, project.id)).get()?.latest ?? null;
+    return {
+      rows: rows.map((r) => ({
+        date: r.date,
+        query: r.query,
+        page: r.page,
+        country: r.country,
+        device: r.device,
+        clicks: r.clicks,
+        impressions: r.impressions,
+        ctr: parseFloat(r.ctr),
+        position: parseFloat(r.position)
+      })),
+      totalMatching,
+      // Account for the offset: `rows.length < totalMatching` alone reports
+      // truncated=true for a page that sits past the end, where there is
+      // nothing further to fetch. Truncation means "more rows follow this
+      // page", so it has to measure from where this page ends.
+      truncated: offsetVal + rows.length < totalMatching,
+      latestAvailableDate
+    };
   });
   app.get("/projects/:name/google/gsc/performance/daily", async (request) => {
     const project = resolveProject(app.db, request.params.name);
@@ -25837,6 +26016,56 @@ async function googleRoutes(app, opts) {
       daily
     };
   });
+  app.get("/projects/:name/google/gsc/top-pages", async (request) => {
+    const project = resolveProject(app.db, request.params.name);
+    const { startDate, endDate, limit } = request.query;
+    const cutoffDate = !startDate ? windowCutoff(parseWindow(request.query.window))?.slice(0, 10) ?? null : null;
+    const conditions = [eq27(gscSearchData.projectId, project.id)];
+    if (startDate) conditions.push(sql12`${gscSearchData.date} >= ${startDate}`);
+    else if (cutoffDate) conditions.push(sql12`${gscSearchData.date} >= ${cutoffDate}`);
+    if (endDate) conditions.push(sql12`${gscSearchData.date} <= ${endDate}`);
+    const limitVal = Math.max(parseInt(limit ?? "50", 10) || 0, 1);
+    const rows = app.db.select({
+      page: gscSearchData.page,
+      clicks: sql12`COALESCE(SUM(${gscSearchData.clicks}), 0)`,
+      impressions: sql12`COALESCE(SUM(${gscSearchData.impressions}), 0)`
+    }).from(gscSearchData).where(and21(...conditions)).groupBy(gscSearchData.page).orderBy(desc13(sql12`SUM(${gscSearchData.clicks})`), desc13(sql12`SUM(${gscSearchData.impressions})`)).limit(limitVal).all();
+    const windowStart = startDate ?? cutoffDate ?? "";
+    const windowEnd = endDate ?? "9999-12-31";
+    const dailyTotals = readGscDailyTotals(app.db, project.id, windowStart, windowEnd);
+    const totalClicks = dailyTotals.reduce((sum, d) => sum + d.clicks, 0);
+    const totalImpressions = dailyTotals.reduce((sum, d) => sum + d.impressions, 0);
+    const rankedSpan = app.db.select({
+      first: sql12`MIN(${gscSearchData.date})`,
+      last: sql12`MAX(${gscSearchData.date})`
+    }).from(gscSearchData).where(and21(...conditions)).get();
+    const coveredFrom = dailyTotals.length > 0 ? dailyTotals[0].date : null;
+    const coveredThrough = dailyTotals.length > 0 ? dailyTotals[dailyTotals.length - 1].date : null;
+    const totalsComplete = Boolean(
+      coveredFrom && coveredThrough && rankedSpan?.first && rankedSpan?.last && coveredFrom <= rankedSpan.first && coveredThrough >= rankedSpan.last
+    );
+    return {
+      rows: rows.map((r) => ({
+        page: r.page,
+        clicks: r.clicks,
+        impressions: r.impressions,
+        ctr: r.impressions > 0 ? r.clicks / r.impressions : 0
+      })),
+      totals: dailyTotals.length > 0 ? {
+        clicks: totalClicks,
+        impressions: totalImpressions,
+        ctr: totalImpressions > 0 ? totalClicks / totalImpressions : 0,
+        days: dailyTotals.length,
+        coveredFrom,
+        coveredThrough,
+        // False when the property-level totals span less than the rows above.
+        complete: totalsComplete
+      } : null,
+      totalsSource: "property-daily",
+      rankedFrom: rankedSpan?.first ?? null,
+      rankedThrough: rankedSpan?.last ?? null
+    };
+  });
   app.post("/projects/:name/google/gsc/inspect", async (request) => {
     const { clientId: googleClientId, clientSecret: googleClientSecret } = getAuthConfig();
     if (!googleClientId || !googleClientSecret) {
@@ -32598,6 +32827,12 @@ function formatSharePct(numerator, total) {
   if (rounded === 0) return "<1%";
   return `${rounded}%`;
 }
+function dateRangeConditions(column, range) {
+  const conditions = [];
+  if (range.startDate) conditions.push(sql15`${column} >= ${range.startDate}`);
+  if (range.endDate) conditions.push(sql15`${column} <= ${range.endDate}`);
+  return conditions;
+}
 var SOCIAL_CHANNEL_GROUPS2 = /* @__PURE__ */ new Set(["Organic Social", "Paid Social"]);
 function buildChannelBreakdown(input) {
   const aiSessions = [...input.aiSessionsByChannelGroup.values()].reduce((sum, sessions) => sum + sessions, 0);
@@ -33054,6 +33289,12 @@ async function ga4Routes(app, opts) {
             date: row.date,
             sessions: row.sessions,
             users: row.users,
+            // Stored as given, nulls included: an absent reading is not a 0%
+            // engagement day. No returning-users figure is derived here —
+            // it is derived from `users - newUsers` at read time so the stored
+            // row keeps only what GA4 actually reported.
+            engagementRate: row.engagementRate,
+            newUsers: row.newUsers,
             syncedAt: now,
             syncRunId: runId,
             createdAt: now
@@ -33253,16 +33494,12 @@ async function ga4Routes(app, opts) {
     const project = resolveProject(app.db, request.params.name);
     requireGa4Connection(opts, project.name, project.canonicalDomain);
     const limit = Math.max(1, Math.min(parseInt(request.query.limit ?? "50", 10) || 50, 500));
-    const window = parseWindow(request.query.window);
-    const cutoff = windowCutoff(window);
-    const cutoffDate = cutoff?.slice(0, 10) ?? null;
-    const snapshotConditions = [eq32(gaTrafficSnapshots.projectId, project.id)];
-    if (cutoffDate) snapshotConditions.push(sql15`${gaTrafficSnapshots.date} >= ${cutoffDate}`);
-    const aiConditions = [eq32(gaAiReferrals.projectId, project.id)];
-    if (cutoffDate) aiConditions.push(sql15`${gaAiReferrals.date} >= ${cutoffDate}`);
-    const socialConditions = [eq32(gaSocialReferrals.projectId, project.id)];
-    if (cutoffDate) socialConditions.push(sql15`${gaSocialReferrals.date} >= ${cutoffDate}`);
-    const windowSummaryRow = cutoffDate ? app.db.select({
+    const range = resolveDateRange(request.query);
+    const dateFiltered = range.startDate !== null || range.endDate !== null;
+    const snapshotConditions = [eq32(gaTrafficSnapshots.projectId, project.id), ...dateRangeConditions(gaTrafficSnapshots.date, range)];
+    const aiConditions = [eq32(gaAiReferrals.projectId, project.id), ...dateRangeConditions(gaAiReferrals.date, range)];
+    const socialConditions = [eq32(gaSocialReferrals.projectId, project.id), ...dateRangeConditions(gaSocialReferrals.date, range)];
+    const windowSummaryRow = range.startDate && !range.explicitDates ? app.db.select({
       totalSessions: gaTrafficWindowSummaries.totalSessions,
       totalOrganicSessions: gaTrafficWindowSummaries.totalOrganicSessions,
       totalDirectSessions: gaTrafficWindowSummaries.totalDirectSessions,
@@ -33270,15 +33507,26 @@ async function ga4Routes(app, opts) {
     }).from(gaTrafficWindowSummaries).where(
       and26(
         eq32(gaTrafficWindowSummaries.projectId, project.id),
-        eq32(gaTrafficWindowSummaries.windowKey, window)
+        eq32(gaTrafficWindowSummaries.windowKey, range.window)
       )
     ).get() : null;
-    const snapshotTotalsRow = cutoffDate && !windowSummaryRow ? app.db.select({
-      totalSessions: sql15`COALESCE(SUM(${gaTrafficSnapshots.sessions}), 0)`,
-      totalOrganicSessions: sql15`COALESCE(SUM(${gaTrafficSnapshots.organicSessions}), 0)`,
-      totalUsers: sql15`COALESCE(SUM(${gaTrafficSnapshots.users}), 0)`
-    }).from(gaTrafficSnapshots).where(and26(...snapshotConditions)).get() : null;
-    const summaryRow = cutoffDate ? windowSummaryRow ?? snapshotTotalsRow : app.db.select({
+    const snapshotTotalsRow = dateFiltered && !windowSummaryRow ? (() => {
+      const summed = app.db.select({
+        totalSessions: sql15`COALESCE(SUM(${gaTrafficSnapshots.sessions}), 0)`,
+        totalOrganicSessions: sql15`COALESCE(SUM(${gaTrafficSnapshots.organicSessions}), 0)`,
+        totalUsers: sql15`COALESCE(SUM(${gaTrafficSnapshots.users}), 0)`
+      }).from(gaTrafficSnapshots).where(and26(...snapshotConditions)).get();
+      return {
+        totalSessions: summed?.totalSessions ?? 0,
+        totalOrganicSessions: summed?.totalOrganicSessions ?? 0,
+        // Unavailable for an EXPLICIT calendar range. The rolling-window
+        // fallback keeps its historical summed value: it is wrong for the
+        // same reason, but it predates this branch and correcting it is a
+        // separate, visible behaviour change rather than one bundled here.
+        totalUsers: range.explicitDates ? null : summed?.totalUsers ?? 0
+      };
+    })() : null;
+    const summaryRow = dateFiltered ? windowSummaryRow ?? snapshotTotalsRow : app.db.select({
       totalSessions: gaTrafficSummaries.totalSessions,
       totalOrganicSessions: gaTrafficSummaries.totalOrganicSessions,
       totalUsers: gaTrafficSummaries.totalUsers
@@ -33363,7 +33611,11 @@ async function ga4Routes(app, opts) {
       totalSessions: total,
       totalOrganicSessions,
       totalDirectSessions,
-      totalUsers: summaryRow?.totalUsers ?? 0,
+      // `null` (not 0) when the range has no un-dimensioned aggregate behind
+      // it. GA counts users as a COUNT DISTINCT at the grain requested, so the
+      // landing-page dimensioned sum is inflated, and a 0 would read as
+      // "nobody visited" rather than "not measurable for this range".
+      totalUsers: summaryRow ? summaryRow.totalUsers : 0,
       topPages: rows.map((r) => ({
         landingPage: r.landingPage,
         sessions: r.sessions ?? 0,
@@ -33430,21 +33682,32 @@ async function ga4Routes(app, opts) {
       directSharePctDisplay: formatSharePct(totalDirectSessions, total),
       socialSharePctDisplay: formatSharePct(socialSessions, total),
       lastSyncedAt: latestSync?.syncedAt ?? null,
+      // Report the range that was actually measured, so a caller can tell which
+      // period the totals above belong to.
+      // An EXPLICIT calendar range is reported back verbatim, even when it
+      // covers nothing. Substituting the synced period there labelled an empty
+      // future range with real past dates, so the numbers said "no data" while
+      // the labels named a period that did have data.
+      //
+      // A rolling window still clamps: "last 30 days" is a relative ask, and a
+      // cutoff computed from today can legitimately land after the last synced
+      // date on a stale project. Reporting a start after the end would be its
+      // own nonsense.
       periodStart: (() => {
-        const start = cutoffDate ?? summaryMeta?.periodStart ?? null;
-        const end = summaryMeta?.periodEnd ?? null;
+        if (range.explicitDates) return range.startDate ?? summaryMeta?.periodStart ?? null;
+        const start = range.startDate ?? summaryMeta?.periodStart ?? null;
+        const end = range.endDate ?? summaryMeta?.periodEnd ?? null;
         if (start && end && start > end) return summaryMeta?.periodStart ?? null;
         return start;
       })(),
-      periodEnd: summaryMeta?.periodEnd ?? null
+      periodEnd: range.endDate ?? summaryMeta?.periodEnd ?? null
     };
   });
   app.get("/projects/:name/ga/ai-referral-history", async (request, _reply) => {
     const project = resolveProject(app.db, request.params.name);
     requireGa4Connection(opts, project.name, project.canonicalDomain);
-    const cutoffDate = windowCutoff(parseWindow(request.query.window))?.slice(0, 10) ?? null;
-    const conditions = [eq32(gaAiReferrals.projectId, project.id)];
-    if (cutoffDate) conditions.push(sql15`${gaAiReferrals.date} >= ${cutoffDate}`);
+    const range = resolveDateRange(request.query);
+    const conditions = [eq32(gaAiReferrals.projectId, project.id), ...dateRangeConditions(gaAiReferrals.date, range)];
     const rows = app.db.select({
       date: gaAiReferrals.date,
       source: gaAiReferrals.source,
@@ -33467,9 +33730,8 @@ async function ga4Routes(app, opts) {
   app.get("/projects/:name/ga/ai-referral-daily", async (request, _reply) => {
     const project = resolveProject(app.db, request.params.name);
     requireGa4Connection(opts, project.name, project.canonicalDomain);
-    const cutoffDate = windowCutoff(parseWindow(request.query.window))?.slice(0, 10) ?? null;
-    const conditions = [eq32(gaAiReferrals.projectId, project.id)];
-    if (cutoffDate) conditions.push(sql15`${gaAiReferrals.date} >= ${cutoffDate}`);
+    const range = resolveDateRange(request.query);
+    const conditions = [eq32(gaAiReferrals.projectId, project.id), ...dateRangeConditions(gaAiReferrals.date, range)];
     const rows = app.db.select({
       date: gaAiReferrals.date,
       source: gaAiReferrals.source,
@@ -33484,9 +33746,8 @@ async function ga4Routes(app, opts) {
   app.get("/projects/:name/ga/social-referral-history", async (request, _reply) => {
     const project = resolveProject(app.db, request.params.name);
     requireGa4Connection(opts, project.name, project.canonicalDomain);
-    const cutoffDate = windowCutoff(parseWindow(request.query.window))?.slice(0, 10) ?? null;
-    const conditions = [eq32(gaSocialReferrals.projectId, project.id)];
-    if (cutoffDate) conditions.push(sql15`${gaSocialReferrals.date} >= ${cutoffDate}`);
+    const range = resolveDateRange(request.query);
+    const conditions = [eq32(gaSocialReferrals.projectId, project.id), ...dateRangeConditions(gaSocialReferrals.date, range)];
     const rows = app.db.select({
       date: gaSocialReferrals.date,
       source: gaSocialReferrals.source,
@@ -33629,17 +33890,15 @@ async function ga4Routes(app, opts) {
   app.get("/projects/:name/ga/session-history", async (request, _reply) => {
     const project = resolveProject(app.db, request.params.name);
     requireGa4Connection(opts, project.name, project.canonicalDomain);
-    const cutoffDate = windowCutoff(parseWindow(request.query.window))?.slice(0, 10) ?? null;
-    const conditions = [eq32(gaTrafficSnapshots.projectId, project.id)];
-    if (cutoffDate) conditions.push(sql15`${gaTrafficSnapshots.date} >= ${cutoffDate}`);
+    const range = resolveDateRange(request.query);
+    const conditions = [eq32(gaTrafficSnapshots.projectId, project.id), ...dateRangeConditions(gaTrafficSnapshots.date, range)];
     const rows = app.db.select({
       date: gaTrafficSnapshots.date,
       sessions: sql15`SUM(${gaTrafficSnapshots.sessions})`,
       organicSessions: sql15`SUM(${gaTrafficSnapshots.organicSessions})`,
       users: sql15`SUM(${gaTrafficSnapshots.users})`
     }).from(gaTrafficSnapshots).where(and26(...conditions)).groupBy(gaTrafficSnapshots.date).orderBy(gaTrafficSnapshots.date).all();
-    const totalConditions = [eq32(gaDailyTotals.projectId, project.id)];
-    if (cutoffDate) totalConditions.push(sql15`${gaDailyTotals.date} >= ${cutoffDate}`);
+    const totalConditions = [eq32(gaDailyTotals.projectId, project.id), ...dateRangeConditions(gaDailyTotals.date, range)];
     const totals = app.db.select({ date: gaDailyTotals.date, users: gaDailyTotals.users }).from(gaDailyTotals).where(and26(...totalConditions)).all();
     return buildSessionHistory(
       rows.map((r) => ({