@agent-native/core-corpus 0.210.2 → 0.211.0

package/corpus/templates/analytics/seeds/dashboards/content-view.json

@@ -0,0 +1,182 @@
+{
+  "name": "Content",
+  "description": "Blog articles with authors, daily GA4 pageviews, Search Console clicks and impressions, and first-touch signups, from Analytics' daily content collection. Reads only Analytics' own tables, so opening it calls no provider.",
+  "filters": [
+    {
+      "id": "timeRange",
+      "type": "select",
+      "label": "Time range",
+      "default": "28d",
+      "options": [
+        {
+          "value": "7d",
+          "label": "Last 7 days"
+        },
+        {
+          "value": "28d",
+          "label": "Last 28 days"
+        },
+        {
+          "value": "90d",
+          "label": "Last 90 days"
+        },
+        {
+          "value": "all",
+          "label": "All time"
+        }
+      ]
+    }
+  ],
+  "panels": [
+    {
+      "id": "collection-status",
+      "title": "Collection",
+      "chartType": "table",
+      "source": "first-party",
+      "width": 3,
+      "sql": "WITH latest AS ( SELECT step, status, started_at, window_end, error_message FROM ( SELECT step, status, started_at, window_end, error_message, ROW_NUMBER() OVER (PARTITION BY step ORDER BY started_at DESC) AS rn FROM analytics_content_collection_runs ) ranked WHERE rn = 1 ) SELECT CASE step WHEN 'builder_blog' THEN 'Blog articles' WHEN 'ga4' THEN 'GA4 pageviews' WHEN 'search_console' THEN 'Search Console' WHEN 'signups' THEN 'Signups' ELSE step END AS source, CASE status WHEN 'succeeded' THEN 'Collected' WHEN 'failed' THEN 'Failed' WHEN 'cost_limited' THEN 'Cost-limited' WHEN 'not_configured' THEN 'Not set up' WHEN 'running' THEN 'Running' ELSE status END AS status, started_at AS last_run, (SELECT window_end FROM analytics_content_collection_runs successful WHERE successful.step = latest.step AND successful.status = 'succeeded' ORDER BY successful.started_at DESC LIMIT 1) AS data_through, error_message AS detail FROM latest ORDER BY CASE step WHEN 'builder_blog' THEN 1 WHEN 'ga4' THEN 2 WHEN 'search_console' THEN 3 WHEN 'signups' THEN 4 ELSE 5 END",
+      "config": {
+        "timeScope": "all-time",
+        "description": "Latest run across all time for each source. Data through is the last successful coverage boundary.",
+        "columns": [
+          {
+            "key": "source",
+            "label": "Source"
+          },
+          {
+            "key": "status",
+            "label": "Status"
+          },
+          {
+            "key": "last_run",
+            "label": "Last run",
+            "format": "date"
+          },
+          {
+            "key": "data_through",
+            "label": "Data through"
+          },
+          {
+            "key": "detail",
+            "label": "Detail"
+          }
+        ]
+      }
+    },
+    {
+      "id": "articles",
+      "title": "Articles",
+      "chartType": "table",
+      "source": "first-party",
+      "width": 3,
+      "sql": "WITH latest AS ( SELECT step, status, started_at, window_end, error_message FROM ( SELECT step, status, started_at, window_end, error_message, ROW_NUMBER() OVER (PARTITION BY step ORDER BY started_at DESC) AS rn FROM analytics_content_collection_runs ) ranked WHERE rn = 1 ), totals AS ( SELECT item_id, SUM(value) FILTER (WHERE metric = 'ga4_pageviews') AS pageviews, COUNT(*) FILTER (WHERE metric = 'ga4_pageviews') AS pageview_rows, SUM(value) FILTER (WHERE metric = 'search_console_clicks') AS clicks, SUM(value) FILTER (WHERE metric = 'search_console_impressions') AS impressions, COUNT(*) FILTER (WHERE metric = 'search_console_clicks') AS search_rows, SUM(value) FILTER (WHERE metric = 'signups_first_touch') AS signups, SUM(value) FILTER (WHERE metric = 'signups_first_touch_source') AS source_signups, COUNT(*) FILTER (WHERE metric = 'signups_first_touch') AS signup_rows FROM analytics_content_metric_snapshots WHERE (metric_date <= to_char(CURRENT_DATE, 'YYYY-MM-DD') AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND metric_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '28d' AND metric_date >= to_char(CURRENT_DATE - INTERVAL '28 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND metric_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = 'custom' AND metric_date >= '{{timeRangeStart}}' AND metric_date <= '{{timeRangeEnd}}'))) GROUP BY item_id ) SELECT title, href, author, published, pageviews, clicks, impressions, signups, source_signups, NULLIF(COALESCE(ga4_missing, '') || CASE WHEN ga4_missing IS NOT NULL AND search_missing IS NOT NULL THEN ' · ' ELSE '' END || COALESCE(search_missing, '') || CASE WHEN signups_missing IS NOT NULL AND (ga4_missing IS NOT NULL OR search_missing IS NOT NULL) THEN ' · ' ELSE '' END || COALESCE(signups_missing, ''), '') AS not_collected FROM ( SELECT i.title, i.url AS href, i.author, i.published_at, substr(i.published_at, 1, 10) AS published, t.pageviews, t.clicks, t.impressions, t.signups, t.source_signups, CASE WHEN COALESCE(t.pageview_rows, 0) > 0 THEN NULL ELSE 'GA4: ' || CASE ga4_run.status WHEN 'failed' THEN 'failed' WHEN 'cost_limited' THEN 'cost-limited' WHEN 'not_configured' THEN 'not set up' WHEN 'running' THEN 'running' WHEN 'succeeded' THEN 'not reported in this window' ELSE 'not collected yet' END END AS ga4_missing, CASE WHEN COALESCE(t.search_rows, 0) > 0 THEN NULL ELSE 'Search Console: ' || CASE search_run.status WHEN 'failed' THEN 'failed' WHEN 'cost_limited' THEN 'cost-limited' WHEN 'not_configured' THEN 'not set up' WHEN 'running' THEN 'running' WHEN 'succeeded' THEN 'not reported in this window' ELSE 'not collected yet' END END AS search_missing, CASE WHEN COALESCE(t.signup_rows, 0) > 0 THEN NULL ELSE 'Signups: ' || CASE signups_run.status WHEN 'failed' THEN 'failed' WHEN 'cost_limited' THEN 'cost-limited' WHEN 'not_configured' THEN 'not set up' WHEN 'running' THEN 'running' WHEN 'succeeded' THEN 'not reported in this window' ELSE 'not collected yet' END END AS signups_missing FROM analytics_content_items i LEFT JOIN totals t ON t.item_id = i.id LEFT JOIN latest ga4_run ON ga4_run.step = 'ga4' LEFT JOIN latest search_run ON search_run.step = 'search_console' LEFT JOIN latest signups_run ON signups_run.step = 'signups' WHERE i.source = 'builder_blog' ) articles ORDER BY published_at DESC NULLS LAST LIMIT 1000",
+      "config": {
+        "timeScope": "dashboard",
+        "description": "The 1,000 most recently published collected blog articles. A blank number means that source has no data for the article in this window; Not collected says why.",
+        "sortable": true,
+        "columns": [
+          {
+            "key": "title",
+            "label": "Article",
+            "format": "link",
+            "linkKey": "href"
+          },
+          {
+            "key": "href",
+            "hidden": true
+          },
+          {
+            "key": "author",
+            "label": "Author"
+          },
+          {
+            "key": "published",
+            "label": "Published"
+          },
+          {
+            "key": "pageviews",
+            "label": "Pageviews",
+            "format": "number"
+          },
+          {
+            "key": "clicks",
+            "label": "Search clicks",
+            "format": "number"
+          },
+          {
+            "key": "impressions",
+            "label": "Impressions",
+            "format": "number"
+          },
+          {
+            "key": "signups",
+            "label": "Signups",
+            "format": "number"
+          },
+          {
+            "key": "source_signups",
+            "label": "Source signups",
+            "format": "number"
+          },
+          {
+            "key": "not_collected",
+            "label": "Not collected"
+          }
+        ]
+      }
+    },
+    {
+      "id": "daily-trend",
+      "title": "Daily pageviews and search clicks",
+      "chartType": "line",
+      "source": "first-party",
+      "width": 3,
+      "sql": "WITH RECURSIVE dates AS (SELECT CASE '{{timeRange}}' WHEN '7d' THEN CURRENT_DATE - 7 WHEN '28d' THEN CURRENT_DATE - 28 WHEN '90d' THEN CURRENT_DATE - 90 WHEN 'custom' THEN NULLIF('{{timeRangeStart}}', '')::date ELSE (SELECT MIN(metric_date)::date FROM analytics_content_metric_snapshots) END AS day UNION ALL SELECT day + 1 FROM dates WHERE day < CASE WHEN '{{timeRange}}' = 'custom' THEN LEAST(CURRENT_DATE, NULLIF('{{timeRangeEnd}}', '')::date) ELSE CURRENT_DATE END), totals AS (SELECT s.metric_date AS date, SUM(s.value) FILTER (WHERE s.metric = 'ga4_pageviews') AS pageviews, SUM(s.value) FILTER (WHERE s.metric = 'search_console_clicks') AS search_clicks FROM analytics_content_metric_snapshots s JOIN analytics_content_items i ON i.id = s.item_id WHERE i.source = 'builder_blog' AND s.metric IN ('ga4_pageviews', 'search_console_clicks') AND (s.metric_date <= to_char(CURRENT_DATE, 'YYYY-MM-DD') AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND s.metric_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '28d' AND s.metric_date >= to_char(CURRENT_DATE - INTERVAL '28 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND s.metric_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = 'custom' AND s.metric_date >= '{{timeRangeStart}}' AND s.metric_date <= '{{timeRangeEnd}}'))) GROUP BY s.metric_date ORDER BY s.metric_date) SELECT to_char(dates.day, 'YYYY-MM-DD') AS date, totals.pageviews, totals.search_clicks FROM dates LEFT JOIN totals ON totals.date = to_char(dates.day, 'YYYY-MM-DD') WHERE dates.day <= CASE WHEN '{{timeRange}}' = 'custom' THEN LEAST(CURRENT_DATE, NULLIF('{{timeRangeEnd}}', '')::date) ELSE CURRENT_DATE END ORDER BY dates.day",
+      "config": {
+        "timeScope": "dashboard",
+        "xKey": "date",
+        "yKeys": ["pageviews", "search_clicks"],
+        "seriesLabels": {
+          "pageviews": "Pageviews",
+          "search_clicks": "Search clicks"
+        },
+        "description": "All blog articles. A day a source hasn't reported is a gap, not a zero."
+      }
+    },
+    {
+      "id": "search-pages",
+      "title": "Other pages in search",
+      "chartType": "table",
+      "source": "first-party",
+      "width": 3,
+      "sql": "SELECT i.url AS page, i.url AS href, SUM(s.value) FILTER (WHERE s.metric = 'search_console_clicks') AS clicks, SUM(s.value) FILTER (WHERE s.metric = 'search_console_impressions') AS impressions FROM analytics_content_items i JOIN analytics_content_metric_snapshots s ON s.item_id = i.id WHERE i.source = 'search_console' AND (s.metric_date <= to_char(CURRENT_DATE, 'YYYY-MM-DD') AND ('{{timeRange}}' IN ('', 'all') OR ('{{timeRange}}' = '7d' AND s.metric_date >= to_char(CURRENT_DATE - INTERVAL '7 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '28d' AND s.metric_date >= to_char(CURRENT_DATE - INTERVAL '28 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = '90d' AND s.metric_date >= to_char(CURRENT_DATE - INTERVAL '90 days', 'YYYY-MM-DD')) OR ('{{timeRange}}' = 'custom' AND s.metric_date >= '{{timeRangeStart}}' AND s.metric_date <= '{{timeRangeEnd}}'))) GROUP BY i.url ORDER BY clicks DESC NULLS LAST, impressions DESC NULLS LAST LIMIT 200",
+      "config": {
+        "timeScope": "dashboard",
+        "description": "Search Console pages that aren't collected blog articles.",
+        "sortable": true,
+        "columns": [
+          {
+            "key": "page",
+            "label": "Page",
+            "format": "link",
+            "linkKey": "href"
+          },
+          {
+            "key": "href",
+            "hidden": true
+          },
+          {
+            "key": "clicks",
+            "label": "Search clicks",
+            "format": "number"
+          },
+          {
+            "key": "impressions",
+            "label": "Impressions",
+            "format": "number"
+          }
+        ]
+      }
+    }
+  ]
+}

package/corpus/templates/analytics/server/db/schema.ts

@@ -1136,6 +1136,7 @@ export const analyticsContentCollectionRuns = table(
     status: text("status").notNull(),
     windowStart: text("window_start"),
     windowEnd: text("window_end"),
+    configFingerprint: text("config_fingerprint"),
     startedAt: text("started_at").notNull(),
     finishedAt: text("finished_at"),
     rowCount: integer("row_count"),

package/corpus/templates/analytics/server/lib/bi-migration/external-dashboards-store.ts

@@ -107,7 +107,9 @@ const SummarySchema = z.object({
   sourceUpdatedAt: z.string().nullable(),
   status: z.enum(["not_started", "migrating", "migrated", "failed"]),
   targetDashboardId: z.string().nullable(),
+  migratedByEmail: z.string().nullable(),
   migratedByCurrentUser: z.boolean(),
+  canStartImport: z.boolean(),
   canRetryStaleClaim: z.boolean(),
   failureCode: z.enum(EXTERNAL_DASHBOARD_FAILURE_CODES).nullable(),
   providerStatus: z.number().nullable(),
@@ -251,20 +253,35 @@ function requireExternalDashboardContext(): ExternalDashboardContext {
   return { orgId, userEmail };
 }
 
-function toSummary(
+/**
+ * Whether this user may claim the source now; claimExternalDashboard applies
+ * the same rule in SQL. Anyone who can open the workbook may start it, retry a
+ * failed import, or take over a stuck one. A source that already has a
+ * dashboard (a re-import, failed or stuck) stays with its migrator.
+ */
+function canStartImport(
   row: ExternalDashboardRow,
-  userEmail: string,
-): ExternalDashboardSummary {
-  const migratedByCurrentUser =
-    row.originalMigratorEmail?.trim().toLowerCase() === userEmail;
+  migratedByCurrentUser: boolean,
+): boolean {
+  if (row.targetDashboardId !== null && !migratedByCurrentUser) return false;
+  if (row.status === "not_started" || row.status === "failed") return true;
   const migrationClaimedAt = row.migrationClaimedAt
     ? Date.parse(row.migrationClaimedAt)
     : Number.NaN;
-  const canRetryStaleClaim =
+  return (
     row.status === "migrating" &&
-    migratedByCurrentUser &&
     Number.isFinite(migrationClaimedAt) &&
-    migrationClaimedAt <= Date.now() - EXTERNAL_DASHBOARD_CLAIM_STALE_AFTER_MS;
+    migrationClaimedAt <= Date.now() - EXTERNAL_DASHBOARD_CLAIM_STALE_AFTER_MS
+  );
+}
+
+function toSummary(
+  row: ExternalDashboardRow,
+  userEmail: string,
+): ExternalDashboardSummary {
+  const migratedByCurrentUser =
+    row.originalMigratorEmail?.trim().toLowerCase() === userEmail;
+  const startable = canStartImport(row, migratedByCurrentUser);
   return SummarySchema.parse({
     id: row.id,
     provider: row.provider,
@@ -272,9 +289,19 @@ function toSummary(
     sourceName: row.sourceName,
     sourceUpdatedAt: row.sourceUpdatedAt,
     status: row.status,
-    targetDashboardId: migratedByCurrentUser ? row.targetDashboardId : null,
+    // Org members see where a migrated source landed so nobody migrates it
+    // twice. Opening the dashboard still goes through its own access check.
+    targetDashboardId:
+      migratedByCurrentUser || row.status === "migrated"
+        ? row.targetDashboardId
+        : null,
+    migratedByEmail:
+      row.status === "migrated" || row.status === "migrating"
+        ? (row.originalMigratorEmail?.trim().toLowerCase() ?? null)
+        : null,
     migratedByCurrentUser,
-    canRetryStaleClaim,
+    canStartImport: startable,
+    canRetryStaleClaim: row.status === "migrating" && startable,
     failureCode: row.failureCode,
     providerStatus: row.providerStatus,
     elementDiagnostics: JSON.parse(row.elementDiagnostics),
@@ -392,14 +419,17 @@ export async function claimExternalDashboard(input: {
   const claimToken = randomUUID();
   const table = schema.externalDashboardMigrations;
   const sameMigrator = eq(table.originalMigratorEmail, userEmail);
-  const canStart = or(
-    eq(table.status, "not_started"),
-    eq(table.status, "failed"),
+  // The SQL form of canStartImport: a source that already has a dashboard
+  // stays with its migrator.
+  const openToCaller = or(isNull(table.targetDashboardId), sameMigrator);
+  const canStart = and(
+    or(eq(table.status, "not_started"), eq(table.status, "failed")),
+    openToCaller,
   );
   const canRecoverStaleClaim = and(
     eq(table.status, "migrating"),
     lt(table.migrationClaimedAt, staleBefore),
-    sameMigrator,
+    openToCaller,
   );
   const canRemigrate = parsed.remigrate
     ? and(eq(table.status, "migrated"), sameMigrator)
@@ -421,7 +451,6 @@ export async function claimExternalDashboard(input: {
         eq(table.orgId, orgId),
         eq(table.provider, parsed.provider),
         eq(table.sourceId, parsed.sourceId),
-        or(isNull(table.originalMigratorEmail), sameMigrator),
         or(canStart, canRecoverStaleClaim, canRemigrate),
       ),
     )
@@ -444,16 +473,25 @@ export async function claimExternalDashboard(input: {
     .limit(1);
   if (!existing) return { claimed: false, reason: "not_found" };
 
+  const existingByCaller =
+    existing.originalMigratorEmail?.trim().toLowerCase() === userEmail;
   if (
-    existing.originalMigratorEmail &&
-    existing.originalMigratorEmail.toLowerCase() !== userEmail
+    existing.status === "failed" &&
+    existing.targetDashboardId !== null &&
+    !existingByCaller
   ) {
-    fail("Only the original migrator may retry or remigrate this source.", {
+    fail("Only the person who migrated this workbook can re-import it.", {
       errorCode: "original_migrator_required",
       statusCode: 403,
     });
   }
   if (existing.status === "migrated") {
+    if (parsed.remigrate && !existingByCaller) {
+      fail("Only the person who migrated this workbook can re-import it.", {
+        errorCode: "original_migrator_required",
+        statusCode: 403,
+      });
+    }
     return { claimed: false, reason: "already_migrated" };
   }
   return { claimed: false, reason: "in_progress" };

package/corpus/templates/analytics/server/lib/bi-migration/unfinished-import.ts

@@ -0,0 +1,64 @@
+import { isActionContractError } from "@agent-native/core/action";
+
+import { removeDashboard } from "../dashboards-store.js";
+import {
+  failExternalDashboard,
+  listExternalDashboards,
+  type ExternalDashboardFailureCode,
+} from "./external-dashboards-store.js";
+
+/**
+ * Record a Sigma import that did not finish, and delete the dashboard it wrote
+ * when that dashboard would otherwise be left behind. Only a first import's
+ * dashboard is deleted. When the claimed record already had a dashboard (a
+ * re-import, a recovery, or a retry of either), this run wrote over the
+ * migrator's own dashboard, which the mapping row still tracks.
+ *
+ * Dashboard ids include the importer's email. So when another person has
+ * taken over the claim, this run's dashboard is never theirs and is deleted;
+ * when the same person took it over, the id is shared and is kept.
+ */
+export async function abandonSigmaImport(input: {
+  workbookId: string;
+  claimToken: string;
+  failureCode: ExternalDashboardFailureCode;
+  dashboardId: string;
+  wroteDashboard: boolean;
+  /** The claimed record's targetDashboardId, not the request's flags. */
+  previousDashboardId: string | null;
+  ctx: { email: string; orgId: string };
+}): Promise<void> {
+  let claimLost: unknown = null;
+  try {
+    await failExternalDashboard({
+      provider: "sigma",
+      sourceId: input.workbookId,
+      claimToken: input.claimToken,
+      failureCode: input.failureCode,
+      preservePreviousMigration: !input.wroteDashboard,
+    });
+  } catch (error) {
+    if (
+      !isActionContractError(error) ||
+      error.errorCode !== "migration_claim_expired"
+    ) {
+      throw error;
+    }
+    claimLost = error;
+  }
+
+  if (input.wroteDashboard && input.previousDashboardId === null) {
+    let orphaned = true;
+    if (claimLost) {
+      const [migration] = await listExternalDashboards({
+        provider: "sigma",
+        sourceIds: [input.workbookId],
+        limit: 1,
+      });
+      orphaned = !migration?.migratedByCurrentUser;
+    }
+    if (orphaned) await removeDashboard(input.dashboardId, input.ctx);
+  }
+
+  if (claimLost) throw claimLost;
+}

package/corpus/templates/analytics/server/lib/builtin-dashboard-pass.ts

@@ -19,6 +19,7 @@ import {
   withoutInstallTimes,
   type BuiltinDashboardInstall,
 } from "./builtin-dashboards";
+import legacyContentView from "./content-metrics/legacy-content-view.json";
 import { materializeLegacyBuiltinDashboardSettings } from "./legacy-builtin-dashboard-settings";
 import {
   nativeV2DashboardManifests,
@@ -169,6 +170,7 @@ function candidateFilter() {
     or(
       sql`${d.id} LIKE 'demo-node-exporter-%'`,
       sql`${d.id} LIKE 'native-%'`,
+      sql`${d.id} LIKE 'content-view-%'`,
       eq(d.id, "risk-meeting"),
       inArray(d.id, [...SEED_BUILTIN_DASHBOARD_IDS]),
       ...SEED_BUILTIN_DASHBOARD_IDS.map(
@@ -309,10 +311,23 @@ export async function runBuiltinDashboardPass(
       const built = install ? buildBuiltinDashboard(builtinId, install) : null;
       if (config && !built) reasons.push("unrecognized");
       if (config && built) {
+        const shippedConfigs = [built.config];
+        if (builtinId === "content-view") {
+          shippedConfigs.push({
+            ...legacyContentView,
+            catalog: {
+              templateId: "content-view",
+              templateVersion: "2026-06-08",
+            },
+          });
+        }
         const same =
           row.title === built.title &&
-          stable(withoutInstallTimes(config)) ===
-            stable(withoutInstallTimes(built.config));
+          shippedConfigs.some(
+            (shipped) =>
+              stable(withoutInstallTimes(config!)) ===
+              stable(withoutInstallTimes(normalizeDashboardConfig(shipped))),
+          );
         if (!same) {
           reasons.push(
             shippedVersion(config) !== shippedVersion(built.config)

package/corpus/templates/analytics/server/lib/content-metrics/collect.ts

@@ -9,6 +9,7 @@ import { contentRunFailureFromError, type ContentStep } from "./step.js";
 import { builderBlogStep } from "./steps/builder-blog.js";
 import { ga4Step } from "./steps/ga4.js";
 import { searchConsoleStep } from "./steps/search-console.js";
+import { signupsStep } from "./steps/signups.js";
 import {
   closeStaleContentRuns,
   completeContentRun,
@@ -24,6 +25,7 @@ const STEPS: Record<ContentCollectionStepId, ContentStep> = {
   builder_blog: builderBlogStep,
   ga4: ga4Step,
   search_console: searchConsoleStep,
+  signups: signupsStep,
 };
 
 export type ContentStepRunSummary = {

package/corpus/templates/analytics/server/lib/content-metrics/config.ts

@@ -1,5 +1,11 @@
 import { z } from "zod";
 
+import {
+  normalizeSearchConsoleProperty,
+  searchConsolePropertyMessage,
+  searchConsolePropertyProblem,
+} from "../../../shared/search-console-property.js";
+
 /**
  * Collection steps, in the order the daily job runs them. A step's id is the
  * `step` stored on its collection runs and the `source` on what it writes.
@@ -8,6 +14,7 @@ export const CONTENT_COLLECTION_STEPS = [
   "builder_blog",
   "ga4",
   "search_console",
+  "signups",
 ] as const;
 export type ContentCollectionStepId = (typeof CONTENT_COLLECTION_STEPS)[number];
 
@@ -18,20 +25,100 @@ const stepToggleSchema = z.object({ enabled: z.boolean() });
  * property such as `https://www.example.com/`. `pathPrefix` keeps a large
  * site to the pages the Content view tracks.
  */
-export const searchConsoleSiteSchema = z.object({
-  siteUrl: z.string().trim().min(1),
+export const storedSearchConsoleSiteSchema = z.object({
+  siteUrl: z.string().trim().min(1).transform(normalizeSearchConsoleProperty),
   pathPrefix: z.string().trim().startsWith("/").optional(),
 });
+
+// Existing configs must stay readable so admins can correct or disable them.
+export const searchConsoleSiteSchema = storedSearchConsoleSiteSchema.extend({
+  siteUrl: storedSearchConsoleSiteSchema.shape.siteUrl.superRefine(
+    (siteUrl, ctx) => {
+      const problem = searchConsolePropertyProblem(siteUrl);
+      if (problem) {
+        ctx.addIssue({
+          code: "custom",
+          message: searchConsolePropertyMessage(siteUrl, problem),
+        });
+      }
+    },
+  ),
+});
 export type SearchConsoleSite = z.infer<typeof searchConsoleSiteSchema>;
 
+const bigQueryTableSchema = z
+  .string()
+  .trim()
+  .regex(
+    /^[A-Za-z0-9_-]+.[A-Za-z0-9_]+.[A-Za-z0-9_]+$/,
+    "Use project.dataset.table",
+  );
+
+const signupSourceSchema = z
+  .string()
+  .trim()
+  .regex(/^[a-z0-9_-]+$/);
+
+/**
+ * The per-article signups join reads the warehouse, so it stays off until an
+ * admin names its tables and a bytes cap measured by a dry run.
+ */
+export const signupsConfigSchema = z.object({
+  enabled: z.boolean(),
+  /** Signup events with JSON `data` holding `visitorId`, `userId` and `signupSource`. */
+  signupEventsTable: bigQueryTableSchema.nullable().default(null),
+  /** One row per visitor's first pageview: `url`, `visitor_id`, `is_bot`, `created_date`. */
+  firstPageviewsTable: bigQueryTableSchema.nullable().default(null),
+  signupSource: signupSourceSchema.nullable().default(null),
+  /** Earliest signup counted, as YYYY-MM-DD; it bounds the events scan. */
+  signupsSince: z.iso.date().nullable().default(null),
+  maxBytesBilled: z
+    .number()
+    .int()
+    .positive()
+    .max(750_000_000_000)
+    .nullable()
+    .default(null),
+});
+
+/**
+ * A change to the signups settings: only the fields given. No defaults, so
+ * merging it over the saved settings never resets one that was left out.
+ */
+export const signupsSettingsUpdateSchema = z.object({
+  enabled: z.boolean().optional(),
+  signupEventsTable: bigQueryTableSchema.nullable().optional(),
+  firstPageviewsTable: bigQueryTableSchema.nullable().optional(),
+  signupSource: signupSourceSchema.nullable().optional(),
+  signupsSince: z.iso.date().nullable().optional(),
+  maxBytesBilled: z
+    .number()
+    .int()
+    .positive()
+    .max(750_000_000_000)
+    .nullable()
+    .optional(),
+});
+export type SignupsConfig = z.infer<typeof signupsConfigSchema>;
+
 export const contentCollectionConfigSchema = z.object({
   builderBlog: stepToggleSchema.default({ enabled: true }),
   ga4: stepToggleSchema.default({ enabled: true }),
   // Off until a property owner grants the service account access; a run
   // before then would only record "no access".
   searchConsole: stepToggleSchema
-    .extend({ sites: z.array(searchConsoleSiteSchema).max(20).default([]) })
+    .extend({
+      sites: z.array(storedSearchConsoleSiteSchema).max(20).default([]),
+    })
     .default({ enabled: false, sites: [] }),
+  signups: signupsConfigSchema.default({
+    enabled: false,
+    signupEventsTable: null,
+    firstPageviewsTable: null,
+    signupSource: null,
+    signupsSince: null,
+    maxBytesBilled: null,
+  }),
 });
 
 export type ContentCollectionConfig = z.infer<
@@ -53,6 +140,8 @@ export function stepEnabled(
       return config.ga4.enabled;
     case "search_console":
       return config.searchConsole.enabled;
+    case "signups":
+      return config.signups.enabled;
   }
 }