@squadbase/vite-server 0.1.17-dev.3b633bb → 0.1.17-dev.71a85cd

package/dist/connectors/google-analytics.js

@@ -16,6 +16,7 @@ var init_parameter_definition = __esm({
       type;
       secret;
       required;
+      isDeprecated;
       constructor(config) {
         this.slug = config.slug;
         this.name = config.name;
@@ -24,6 +25,7 @@ var init_parameter_definition = __esm({
         this.type = config.type;
         this.secret = config.secret;
         this.required = config.required;
+        this.isDeprecated = config.isDeprecated ?? false;
       }
       /**
        * Get the parameter value from a ConnectorConnectionObject.
@@ -67,6 +69,16 @@ var parameters = {
     type: "base64EncodedJson",
     secret: true,
     required: true
+  }),
+  propertyId: new ParameterDefinition({
+    slug: "property-id",
+    name: "Google Analytics Property ID",
+    description: "The Google Analytics 4 property ID (e.g., 123456789). Automatically set during the setup flow.",
+    envVarBaseKey: "GA_PROPERTY_ID",
+    type: "text",
+    secret: false,
+    required: false,
+    isDeprecated: true
   })
 };
 
@@ -98,6 +110,7 @@ function buildJwt(clientEmail, privateKey, nowSec) {
 }
 function createClient(params) {
   const serviceAccountKeyJsonBase64 = params[parameters.serviceAccountKeyJsonBase64.slug];
+  const defaultPropertyId = params["property-id"] ?? "";
   if (!serviceAccountKeyJsonBase64) {
     throw new Error(
       `google-analytics: missing required parameters: ${parameters.serviceAccountKeyJsonBase64.slug}`
@@ -159,13 +172,18 @@ function createClient(params) {
       headers.set("Authorization", `Bearer ${accessToken}`);
       return fetch(url, { ...init, headers });
     },
-    async runReport(propertyId, request) {
+    async runReport(request) {
+      const { propertyId: pid, ...body } = request;
+      const propertyId = pid || defaultPropertyId;
+      if (!propertyId) {
+        throw new Error("google-analytics: propertyId is required in runReport request");
+      }
       const response = await this.request(
         `properties/${propertyId}:runReport`,
         {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(request)
+          body: JSON.stringify(body)
         }
       );
       if (!response.ok) {
@@ -180,7 +198,11 @@ function createClient(params) {
         rowCount: data.rowCount ?? 0
       };
     },
-    async getMetadata(propertyId) {
+    async getMetadata(request) {
+      const propertyId = request.propertyId || defaultPropertyId;
+      if (!propertyId) {
+        throw new Error("google-analytics: propertyId is required in getMetadata request");
+      }
       const response = await this.request(
         `properties/${propertyId}/metadata`,
         { method: "GET" }
@@ -193,13 +215,18 @@ function createClient(params) {
       }
       return await response.json();
     },
-    async runRealtimeReport(propertyId, request) {
+    async runRealtimeReport(request) {
+      const { propertyId: pid, ...body } = request;
+      const propertyId = pid || defaultPropertyId;
+      if (!propertyId) {
+        throw new Error("google-analytics: propertyId is required in runRealtimeReport request");
+      }
       const response = await this.request(
         `properties/${propertyId}:runRealtimeReport`,
         {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(request)
+          body: JSON.stringify(body)
         }
       );
       if (!response.ok) {
@@ -323,7 +350,7 @@ var ConnectorPlugin = class _ConnectorPlugin {
   /**
    * Create tools for connections that belong to this connector.
    * Filters connections by connectorKey internally.
-   * Returns tools keyed as `${connectorKey}_${toolName}`.
+   * Returns tools keyed as `connector_${connectorKey}_${toolName}`.
    */
   createTools(connections, config, opts) {
     const myConnections = connections.filter(
@@ -333,7 +360,7 @@ var ConnectorPlugin = class _ConnectorPlugin {
     for (const t of Object.values(this.tools)) {
       const tool = t.createTool(myConnections, config);
       const originalToModelOutput = tool.toModelOutput;
-      result[`${this.connectorKey}_${t.name}`] = {
+      result[`connector_${this.connectorKey}_${t.name}`] = {
         ...tool,
         toModelOutput: async (options) => {
           if (!originalToModelOutput) {
@@ -463,10 +490,10 @@ var AUTH_TYPES = {
 // ../connectors/src/connectors/google-analytics/setup.ts
 var googleAnalyticsOnboarding = new ConnectorOnboarding({
   dataOverviewInstructions: {
-    en: `1. Call google-analytics-service-account_request with GET properties/{propertyId}/metadata to list available dimensions and metrics
-2. Call google-analytics-service-account_request with POST properties/{propertyId}:runReport using a small date range and basic metrics to verify data availability`,
-    ja: `1. google-analytics-service-account_request \u3067 GET properties/{propertyId}/metadata \u3092\u547C\u3073\u51FA\u3057\u3001\u5229\u7528\u53EF\u80FD\u306A\u30C7\u30A3\u30E1\u30F3\u30B7\u30E7\u30F3\u3068\u30E1\u30C8\u30EA\u30AF\u30B9\u306E\u4E00\u89A7\u3092\u53D6\u5F97
-2. google-analytics-service-account_request \u3067 POST properties/{propertyId}:runReport \u3092\u77ED\u3044\u671F\u9593\u3068\u57FA\u672C\u30E1\u30C8\u30EA\u30AF\u30B9\u3067\u547C\u3073\u51FA\u3057\u3001\u30C7\u30FC\u30BF\u306E\u53EF\u7528\u6027\u3092\u78BA\u8A8D`
+    en: `1. Call connector_google-analytics-service-account_request with GET properties/{propertyId}/metadata to list available dimensions and metrics
+2. Call connector_google-analytics-service-account_request with POST properties/{propertyId}:runReport using a small date range and basic metrics to verify data availability`,
+    ja: `1. connector_google-analytics-service-account_request \u3067 GET properties/{propertyId}/metadata \u3092\u547C\u3073\u51FA\u3057\u3001\u5229\u7528\u53EF\u80FD\u306A\u30C7\u30A3\u30E1\u30F3\u30B7\u30E7\u30F3\u3068\u30E1\u30C8\u30EA\u30AF\u30B9\u306E\u4E00\u89A7\u3092\u53D6\u5F97
+2. connector_google-analytics-service-account_request \u3067 POST properties/{propertyId}:runReport \u3092\u77ED\u3044\u671F\u9593\u3068\u57FA\u672C\u30E1\u30C8\u30EA\u30AF\u30B9\u3067\u547C\u3073\u51FA\u3057\u3001\u30C7\u30FC\u30BF\u306E\u53EF\u7528\u6027\u3092\u78BA\u8A8D`
   }
 });
 
@@ -574,7 +601,17 @@ async function dataFetch(params, path2, init) {
 // ../connectors/src/connectors/google-analytics/setup-flow.ts
 var ALL_PROPERTIES = "__ALL_PROPERTIES__";
 var GOOGLE_ANALYTICS_SETUP_MAX_PROPERTIES = 20;
-var METADATA_DISPLAY_LIMIT = 30;
+var MAX_PROPERTIES_TO_EXPLORE = 2;
+var TOP_N_SOURCES = 8;
+var TOP_N_COUNTRIES = 8;
+var TOP_N_BROWSERS = 5;
+var TOP_N_PAGES = 10;
+var TOP_N_EVENTS = 10;
+var STANDARD_METADATA_LIMIT = 25;
+var CUSTOM_METADATA_LIMIT = 15;
+var DESCRIPTION_MAX = 140;
+var PAGE_PATH_MAX = 80;
+var EVENT_NAME_MAX = 60;
 async function listAccountSummaries(params) {
   const summaries = [];
   let pageToken;
@@ -597,9 +634,13 @@ function propertyIdFromResource(resource) {
   return (resource ?? "").replace(/^properties\//, "");
 }
 async function getProperty(params, propertyId) {
-  const res = await adminFetch(params, `/properties/${propertyId}`);
-  if (!res.ok) return null;
-  return await res.json();
+  try {
+    const res = await adminFetch(params, `/properties/${propertyId}`);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
 }
 async function getMetadata(params, propertyId) {
   try {
@@ -607,41 +648,387 @@ async function getMetadata(params, propertyId) {
       params,
       `/properties/${propertyId}/metadata`
     );
-    if (!res.ok) return { dimensions: [], metrics: [] };
-    const data = await res.json();
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+async function probePropertyAccess(params, propertyId) {
+  try {
+    const res = await dataFetch(
+      params,
+      `/properties/${propertyId}:runReport`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          dateRanges: [{ startDate: "7daysAgo", endDate: "today" }],
+          metrics: [{ name: "activeUsers" }],
+          limit: 1
+        })
+      }
+    );
+    if (res.ok) return { ok: true };
+    const body = await res.text().catch(() => res.statusText);
+    return { ok: false, status: res.status, body };
+  } catch (err) {
     return {
-      dimensions: data.dimensions ?? [],
-      metrics: data.metrics ?? []
+      ok: false,
+      status: "network",
+      body: err instanceof Error ? err.message : String(err)
     };
+  }
+}
+async function batchRunReports(params, propertyId, requests) {
+  try {
+    const res = await dataFetch(
+      params,
+      `/properties/${propertyId}:batchRunReports`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ requests })
+      }
+    );
+    if (!res.ok) return requests.map(() => ({}));
+    const data = await res.json();
+    const reports = data.reports ?? [];
+    return requests.map((_, i) => reports[i] ?? {});
   } catch {
-    return { dimensions: [], metrics: [] };
+    return requests.map(() => ({}));
+  }
+}
+var LAST_30D = { startDate: "30daysAgo", endDate: "today" };
+var PREV_30D = { startDate: "60daysAgo", endDate: "31daysAgo" };
+var HEADLINE_METRICS = [
+  "activeUsers",
+  "newUsers",
+  "sessions",
+  "screenPageViews",
+  "engagementRate",
+  "averageSessionDuration",
+  "keyEvents",
+  "totalRevenue"
+];
+function buildHeadlineRequest() {
+  return {
+    dateRanges: [
+      { ...LAST_30D, name: "current" },
+      { ...PREV_30D, name: "previous" }
+    ],
+    metrics: HEADLINE_METRICS.map((name) => ({ name }))
+  };
+}
+function buildTopDimensionRequest(dimension, metric, limit) {
+  return {
+    dateRanges: [LAST_30D],
+    dimensions: [{ name: dimension }],
+    metrics: [{ name: metric }],
+    limit,
+    orderBys: [{ desc: true, metric: { metricName: metric } }]
+  };
+}
+function buildTopPagesRequest() {
+  return {
+    dateRanges: [LAST_30D],
+    dimensions: [{ name: "pagePath" }],
+    metrics: [
+      { name: "screenPageViews" },
+      { name: "activeUsers" },
+      { name: "averageSessionDuration" }
+    ],
+    limit: TOP_N_PAGES,
+    orderBys: [{ desc: true, metric: { metricName: "screenPageViews" } }]
+  };
+}
+function buildTopEventsRequest() {
+  return {
+    dateRanges: [LAST_30D],
+    dimensions: [{ name: "eventName" }],
+    metrics: [{ name: "eventCount" }, { name: "totalUsers" }],
+    limit: TOP_N_EVENTS,
+    orderBys: [{ desc: true, metric: { metricName: "eventCount" } }]
+  };
+}
+function escapePipe(s) {
+  return s.replace(/\|/g, "\\|");
+}
+function truncate(s, max) {
+  if (!s) return "";
+  if (s.length <= max) return s;
+  return `${s.slice(0, Math.max(0, max - 1))}\u2026`;
+}
+function formatNumber(raw) {
+  if (raw == null || raw === "") return "-";
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return raw;
+  if (Number.isInteger(n)) return n.toLocaleString("en-US");
+  return n.toLocaleString("en-US", { maximumFractionDigits: 2 });
+}
+function formatPercent(raw) {
+  if (raw == null || raw === "") return "-";
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return raw;
+  return `${(n * 100).toFixed(1)}%`;
+}
+function formatDuration(rawSeconds) {
+  if (rawSeconds == null || rawSeconds === "") return "-";
+  const s = Math.round(Number(rawSeconds));
+  if (!Number.isFinite(s)) return rawSeconds;
+  if (s < 60) return `${s}s`;
+  const mins = Math.floor(s / 60);
+  const secs = s % 60;
+  return `${mins}m ${secs}s`;
+}
+function deltaArrow(curr, prev) {
+  if (!Number.isFinite(prev) || prev === 0) return "";
+  const pct = (curr - prev) / prev * 100;
+  if (Math.abs(pct) < 0.5) return " (\u2248 flat)";
+  const sign = pct > 0 ? "\u2191" : "\u2193";
+  return ` (${sign} ${Math.abs(pct).toFixed(1)}% vs prior 30d)`;
+}
+function pivotComparisonReport(report) {
+  const out = /* @__PURE__ */ new Map();
+  const headers = report.metricHeaders ?? [];
+  const rows = report.rows ?? [];
+  for (let i = 0; i < headers.length; i++) {
+    const name = headers[i]?.name;
+    if (!name) continue;
+    out.set(name, {
+      current: Number(rows[0]?.metricValues?.[i]?.value ?? "0"),
+      previous: Number(rows[1]?.metricValues?.[i]?.value ?? "0")
+    });
+  }
+  return out;
+}
+function renderHeadline(sections, report) {
+  const m = pivotComparisonReport(report);
+  if (m.size === 0) return;
+  sections.push("#### Headline metrics (last 30 days)", "");
+  const lines = [];
+  const push = (label, key, formatter) => {
+    const cell = m.get(key);
+    if (!cell) return;
+    const formatted = formatter(String(cell.current));
+    const delta = deltaArrow(cell.current, cell.previous);
+    lines.push([label, `${formatted}${delta}`]);
+  };
+  push("Active users", "activeUsers", formatNumber);
+  push("New users", "newUsers", formatNumber);
+  push("Sessions", "sessions", formatNumber);
+  push("Page / screen views", "screenPageViews", formatNumber);
+  push("Engagement rate", "engagementRate", formatPercent);
+  push("Avg session duration", "averageSessionDuration", formatDuration);
+  push("Key events (conversions)", "keyEvents", formatNumber);
+  const rev = m.get("totalRevenue");
+  if (rev && rev.current > 0) {
+    lines.push([
+      "Total revenue",
+      `${formatNumber(String(rev.current))}${deltaArrow(rev.current, rev.previous)}`
+    ]);
+  }
+  for (const [k, v] of lines) sections.push(`- **${k}**: ${v}`);
+  sections.push("");
+}
+function renderBreakdown(sections, title, blurb, report, topN, metricFormatter = formatNumber) {
+  const rows = report.rows ?? [];
+  if (rows.length === 0) return;
+  const dim = report.dimensionHeaders?.[0]?.name ?? "dimension";
+  const metricName = report.metricHeaders?.[0]?.name ?? "metric";
+  sections.push(`#### ${title}`, "", blurb, "");
+  for (const row of rows.slice(0, topN)) {
+    const label = row.dimensionValues?.[0]?.value || `(empty ${dim})`;
+    const value = metricFormatter(row.metricValues?.[0]?.value);
+    sections.push(`- ${label}: ${value} ${metricName}`);
+  }
+  sections.push("");
+}
+function renderTopPages(sections, report) {
+  const rows = report.rows ?? [];
+  if (rows.length === 0) return;
+  sections.push(
+    `#### Top pages by views (last 30 days)`,
+    "",
+    "_The most-visited pages \u2014 strong candidates for content-performance dashboards._",
+    ""
+  );
+  sections.push("| Path | Page views | Active users | Avg session duration |");
+  sections.push("|------|------------|--------------|----------------------|");
+  for (const row of rows.slice(0, TOP_N_PAGES)) {
+    const path2 = truncate(row.dimensionValues?.[0]?.value, PAGE_PATH_MAX) || "-";
+    sections.push(
+      `| ${escapePipe(path2)} | ${formatNumber(row.metricValues?.[0]?.value)} | ${formatNumber(
+        row.metricValues?.[1]?.value
+      )} | ${formatDuration(row.metricValues?.[2]?.value)} |`
+    );
+  }
+  sections.push("");
+}
+function renderTopEvents(sections, report) {
+  const rows = report.rows ?? [];
+  if (rows.length === 0) return;
+  sections.push(
+    `#### Top events (last 30 days)`,
+    "",
+    "_Standard auto-collected events (`page_view`, `session_start`, \u2026) plus any custom events the team has set up. The custom ones are usually the most interesting for funnel / conversion dashboards._",
+    ""
+  );
+  sections.push("| Event | Event count | Unique users |");
+  sections.push("|-------|-------------|--------------|");
+  for (const row of rows.slice(0, TOP_N_EVENTS)) {
+    const name = truncate(row.dimensionValues?.[0]?.value, EVENT_NAME_MAX) || "-";
+    sections.push(
+      `| \`${escapePipe(name)}\` | ${formatNumber(row.metricValues?.[0]?.value)} | ${formatNumber(
+        row.metricValues?.[1]?.value
+      )} |`
+    );
   }
+  sections.push("");
 }
-function appendMetadataSection(sections, dimensions, metrics) {
-  if (dimensions.length > 0) {
-    sections.push(`#### Dimensions (${dimensions.length})`, "");
-    for (const d of dimensions.slice(0, METADATA_DISPLAY_LIMIT)) {
-      sections.push(`- ${d.apiName ?? d.uiName ?? "(unknown)"}`);
+function renderMetadata(sections, metadata) {
+  const dims = metadata.dimensions ?? [];
+  const mets = metadata.metrics ?? [];
+  if (dims.length === 0 && mets.length === 0) return;
+  const customDims = dims.filter((d) => d.customDefinition);
+  const customMets = mets.filter((m) => m.customDefinition);
+  const standardDims = dims.filter((d) => !d.customDefinition);
+  const standardMets = mets.filter((m) => !m.customDefinition);
+  sections.push("#### Available query surface", "");
+  sections.push(
+    "_Use these in custom `runReport` calls. Custom definitions reveal what the team specifically tracks beyond GA4's defaults._",
+    ""
+  );
+  if (customDims.length > 0 || customMets.length > 0) {
+    sections.push(`##### Custom definitions`, "");
+    for (const d of customDims.slice(0, CUSTOM_METADATA_LIMIT)) {
+      const desc = d.description ? ` \u2014 ${truncate(d.description, DESCRIPTION_MAX)}` : "";
+      sections.push(`- dimension \`${d.apiName ?? d.uiName}\`${desc}`);
     }
-    if (dimensions.length > METADATA_DISPLAY_LIMIT) {
+    if (customDims.length > CUSTOM_METADATA_LIMIT) {
       sections.push(
-        `- \u2026and ${dimensions.length - METADATA_DISPLAY_LIMIT} more`
+        `- _\u2026and ${customDims.length - CUSTOM_METADATA_LIMIT} more custom dimensions._`
       );
     }
-    sections.push("");
-  }
-  if (metrics.length > 0) {
-    sections.push(`#### Metrics (${metrics.length})`, "");
-    for (const m of metrics.slice(0, METADATA_DISPLAY_LIMIT)) {
-      sections.push(`- ${m.apiName ?? m.uiName ?? "(unknown)"}`);
+    for (const m of customMets.slice(0, CUSTOM_METADATA_LIMIT)) {
+      const desc = m.description ? ` \u2014 ${truncate(m.description, DESCRIPTION_MAX)}` : "";
+      sections.push(`- metric \`${m.apiName ?? m.uiName}\`${desc}`);
     }
-    if (metrics.length > METADATA_DISPLAY_LIMIT) {
+    if (customMets.length > CUSTOM_METADATA_LIMIT) {
       sections.push(
-        `- \u2026and ${metrics.length - METADATA_DISPLAY_LIMIT} more`
+        `- _\u2026and ${customMets.length - CUSTOM_METADATA_LIMIT} more custom metrics._`
       );
     }
     sections.push("");
   }
+  if (standardDims.length > 0) {
+    sections.push(`##### Standard dimensions (${standardDims.length})`);
+    const names = standardDims.slice(0, STANDARD_METADATA_LIMIT).map((d) => `\`${d.apiName ?? d.uiName}\``).join(", ");
+    const overflow = standardDims.length > STANDARD_METADATA_LIMIT ? ` _(+${standardDims.length - STANDARD_METADATA_LIMIT} more)_` : "";
+    sections.push(names + overflow, "");
+  }
+  if (standardMets.length > 0) {
+    sections.push(`##### Standard metrics (${standardMets.length})`);
+    const names = standardMets.slice(0, STANDARD_METADATA_LIMIT).map((m) => `\`${m.apiName ?? m.uiName}\``).join(", ");
+    const overflow = standardMets.length > STANDARD_METADATA_LIMIT ? ` _(+${standardMets.length - STANDARD_METADATA_LIMIT} more)_` : "";
+    sections.push(names + overflow, "");
+  }
+}
+function renderProbeFailure(sections, propertyId, probe, serviceAccountEmail) {
+  sections.push(`#### Connection probe failed`, "");
+  if (probe.status === 403) {
+    sections.push(
+      `_The service account could not access GA4 property \`${propertyId}\`._`,
+      "",
+      `**Fix**: In GA4 (Admin > Property access management), grant **Viewer** role to the service account below, then re-run setup.`,
+      ""
+    );
+    if (serviceAccountEmail) {
+      sections.push(`\`${serviceAccountEmail}\``, "");
+    }
+  } else if (probe.status === 404) {
+    sections.push(
+      `_GA4 property \`${propertyId}\` was not found. Double-check the Property ID in **Admin > Property Settings**._`,
+      ""
+    );
+  } else if (probe.status === "network") {
+    sections.push(
+      `_Could not reach the GA4 Data API: ${probe.body}_`,
+      ""
+    );
+  } else {
+    sections.push(
+      `_GA4 Data API returned ${probe.status}: ${probe.body.slice(0, 400)}_`,
+      ""
+    );
+  }
+}
+async function exploreProperty(sections, params, propertyId, serviceAccountEmail) {
+  const probe = await probePropertyAccess(params, propertyId);
+  if (!probe.ok) {
+    renderProbeFailure(sections, propertyId, probe, serviceAccountEmail);
+    return;
+  }
+  const batch1Requests = [
+    buildHeadlineRequest(),
+    buildTopDimensionRequest("sessionSourceMedium", "sessions", TOP_N_SOURCES),
+    buildTopDimensionRequest("country", "activeUsers", TOP_N_COUNTRIES),
+    buildTopDimensionRequest("deviceCategory", "sessions", 5),
+    buildTopDimensionRequest("browser", "activeUsers", TOP_N_BROWSERS)
+  ];
+  const batch2Requests = [buildTopPagesRequest(), buildTopEventsRequest()];
+  const [batch1, batch2, metadata] = await Promise.all([
+    batchRunReports(params, propertyId, batch1Requests),
+    batchRunReports(params, propertyId, batch2Requests),
+    getMetadata(params, propertyId)
+  ]);
+  const [headline, sourceMedium, country, device, browser] = batch1;
+  const [topPages, topEvents] = batch2;
+  if (headline) renderHeadline(sections, headline);
+  const hasTrafficSignal = (sourceMedium?.rows?.length ?? 0) + (country?.rows?.length ?? 0) + (device?.rows?.length ?? 0) + (browser?.rows?.length ?? 0) > 0;
+  if (hasTrafficSignal) {
+    sections.push(
+      "#### Traffic mix (last 30 days)",
+      "",
+      "_Where users are coming from \u2014 useful for dashboards that segment by acquisition channel, geography, or device._",
+      ""
+    );
+    if (sourceMedium)
+      renderBreakdown(
+        sections,
+        "Top source / medium",
+        "_Acquisition channels driving sessions._",
+        sourceMedium,
+        TOP_N_SOURCES
+      );
+    if (country)
+      renderBreakdown(
+        sections,
+        "Top countries by active users",
+        "_Geography \u2014 informs which date/time filters and locale segments to expose._",
+        country,
+        TOP_N_COUNTRIES
+      );
+    if (device)
+      renderBreakdown(
+        sections,
+        "Device categories",
+        "_Desktop / mobile / tablet split \u2014 informs responsive cuts._",
+        device,
+        5
+      );
+    if (browser)
+      renderBreakdown(
+        sections,
+        "Top browsers",
+        "_Browser distribution \u2014 informs compatibility dashboards or QA filters._",
+        browser,
+        TOP_N_BROWSERS
+      );
+  }
+  if (topPages) renderTopPages(sections, topPages);
+  if (topEvents) renderTopEvents(sections, topEvents);
+  if (metadata) renderMetadata(sections, metadata);
 }
 var googleAnalyticsSetupFlow = {
   initialState: () => ({}),
@@ -710,8 +1097,8 @@ var googleAnalyticsSetupFlow = {
       slug: "manualPropertyId",
       type: "text",
       question: {
-        ja: "GA4 \u30D7\u30ED\u30D1\u30C6\u30A3 ID \u3092\u5165\u529B\u3057\u3066\u304F\u3060\u3055\u3044\uFF08\u4F8B: 123456789\uFF09\u3002GA4 \u7BA1\u7406\u753B\u9762 > \u30D7\u30ED\u30D1\u30C6\u30A3\u8A2D\u5B9A\u3067\u78BA\u8A8D\u3067\u304D\u307E\u3059\u3002",
-        en: "Enter your GA4 Property ID (e.g., 123456789). Found in GA4 Admin > Property Settings."
+        ja: "GA4 \u30D7\u30ED\u30D1\u30C6\u30A3 ID \u3092\u5165\u529B\u3057\u3066\u304F\u3060\u3055\u3044\uFF08\u4F8B: 123456789\uFF09\u3002GA4 \u7BA1\u7406\u753B\u9762 > \u30D7\u30ED\u30D1\u30C6\u30A3\u8A2D\u5B9A\u3067\u78BA\u8A8D\u3067\u304D\u307E\u3059\u3002\u5165\u529B\u5F8C\u3001\u30C7\u30FC\u30BF\u53D6\u5F97\u3092\u8A66\u3057\u3066\u30C0\u30C3\u30B7\u30E5\u30DC\u30FC\u30C9\u63D0\u6848\u7528\u306E\u30B5\u30DE\u30EA\u3092\u751F\u6210\u3057\u307E\u3059\u3002",
+        en: "Enter your GA4 Property ID (e.g., 123456789). Found in GA4 Admin > Property Settings. After entry we'll probe the property via the Data API and assemble a dashboard-ready summary."
       },
       async fetchOptions(state) {
         if (state.properties?.length) return [];
@@ -725,85 +1112,107 @@ var googleAnalyticsSetupFlow = {
   ],
   async finalize(state, rt) {
     const sections = ["## Google Analytics", ""];
+    let serviceAccountEmail = null;
+    try {
+      const keyJsonBase64 = rt.params[parameters.serviceAccountKeyJsonBase64.slug];
+      if (keyJsonBase64) {
+        serviceAccountEmail = decodeServiceAccount(keyJsonBase64).client_email ?? null;
+      }
+    } catch {
+    }
+    let targetPropertyIds = [];
+    let accountLabel = null;
+    let accountSummary;
     if (state.account && state.properties) {
-      let summaries = [];
       try {
-        summaries = await listAccountSummaries(rt.params);
+        const summaries = await listAccountSummaries(rt.params);
+        accountSummary = summaries.find(
+          (s) => (s.account ?? s.name) === state.account
+        );
+        accountLabel = accountSummary?.displayName ?? state.account.replace(/^accounts\//, "");
       } catch {
+        accountLabel = state.account.replace(/^accounts\//, "");
       }
-      const account = summaries.find(
-        (s) => (s.account ?? s.name) === state.account
-      );
-      const accountLabel = account?.displayName ?? state.account.replace(/^accounts\//, "");
-      const targetPropertyIds = await resolveSetupSelection({
+      targetPropertyIds = await resolveSetupSelection({
         selected: state.properties,
         allSentinel: ALL_PROPERTIES,
-        fetchAll: async () => (account?.propertySummaries ?? []).map((p) => propertyIdFromResource(p.property)).filter((v) => v),
+        fetchAll: async () => (accountSummary?.propertySummaries ?? []).map((p) => propertyIdFromResource(p.property)).filter((v) => v),
         limit: GOOGLE_ANALYTICS_SETUP_MAX_PROPERTIES
       });
-      sections.push(`### Account: ${accountLabel}`, "");
-      if (targetPropertyIds.length === 0) {
-        sections.push("_No properties selected._", "");
-        return sections.join("\n");
-      }
-      sections.push(
-        "| Property ID | Display Name | Time Zone | Currency | Industry |"
-      );
+    } else if (state.manualPropertyId) {
+      targetPropertyIds = [state.manualPropertyId];
+    }
+    if (targetPropertyIds.length === 0) {
       sections.push(
-        "|-------------|--------------|-----------|----------|----------|"
+        "_Could not identify a target GA4 property. Either enable the Google Analytics Admin API on the service account's GCP project, or re-run setup and provide the Property ID manually._",
+        ""
       );
-      for (const pid of targetPropertyIds) {
-        const prop = await getProperty(rt.params, pid).catch(() => null);
-        const displayName = (prop?.displayName ?? "-").replace(/\|/g, "\\|");
-        const timeZone = prop?.timeZone ?? "-";
-        const currency = prop?.currencyCode ?? "-";
-        const industry = (prop?.industryCategory ?? "-").replace(
-          /\|/g,
-          "\\|"
-        );
+      if (serviceAccountEmail) {
         sections.push(
-          `| ${pid} | ${displayName} | ${timeZone} | ${currency} | ${industry} |`
-        );
-      }
-      sections.push("");
-      const firstPropertyId = targetPropertyIds[0];
-      if (firstPropertyId) {
-        const { dimensions, metrics } = await getMetadata(
-          rt.params,
-          firstPropertyId
+          `_Service account email (share your GA4 property with this address)_: \`${serviceAccountEmail}\``,
+          ""
         );
-        appendMetadataSection(sections, dimensions, metrics);
       }
       return sections.join("\n");
     }
-    const propertyId = state.manualPropertyId;
-    if (propertyId) {
-      sections.push(`### Property: ${propertyId}`, "");
-      const { dimensions, metrics } = await getMetadata(
-        rt.params,
-        propertyId
-      );
-      appendMetadataSection(sections, dimensions, metrics);
-      return sections.join("\n");
-    }
     sections.push(
-      "_Could not list GA4 accounts. Please enable the Google Analytics Admin API in your GCP project. Property ID can be specified per request at runtime._",
+      "_The downstream coding agent should use this summary as the canonical baseline of the property's traffic shape for dashboard / app proposals. Headline metrics, traffic mix, top pages, top events, and custom dimensions/metrics together cover the most common dashboarding patterns; reach for the standard query surface for anything custom._",
       ""
     );
+    if (accountLabel) sections.push(`### Account: ${accountLabel}`, "");
+    sections.push("### Properties", "");
+    sections.push(
+      "| Property ID | Display Name | Time Zone | Currency | Industry |"
+    );
+    sections.push(
+      "|-------------|--------------|-----------|----------|----------|"
+    );
+    const properties = await Promise.all(
+      targetPropertyIds.map((id) => getProperty(rt.params, id))
+    );
+    for (let i = 0; i < targetPropertyIds.length; i++) {
+      const pid = targetPropertyIds[i];
+      const prop = properties[i];
+      const displayName = escapePipe(prop?.displayName ?? "-");
+      const timeZone = prop?.timeZone ?? "-";
+      const currency = prop?.currencyCode ?? "-";
+      const industry = escapePipe(prop?.industryCategory ?? "-");
+      sections.push(
+        `| ${pid} | ${displayName} | ${timeZone} | ${currency} | ${industry} |`
+      );
+    }
+    sections.push("");
+    const propertiesToExplore = targetPropertyIds.slice(
+      0,
+      MAX_PROPERTIES_TO_EXPLORE
+    );
+    for (let i = 0; i < propertiesToExplore.length; i++) {
+      const pid = propertiesToExplore[i];
+      const prop = properties[i];
+      const heading = prop?.displayName && prop.displayName !== "-" ? `### Data exploration: ${prop.displayName} (${pid})` : `### Data exploration: property ${pid}`;
+      sections.push(heading, "");
+      await exploreProperty(sections, rt.params, pid, serviceAccountEmail);
+    }
+    if (targetPropertyIds.length > propertiesToExplore.length) {
+      const skipped = targetPropertyIds.length - propertiesToExplore.length;
+      sections.push(
+        `_Deep exploration limited to the first ${propertiesToExplore.length} of ${targetPropertyIds.length} properties to keep this summary bounded. The remaining ${skipped} can be explored on demand via \`connector_google-analytics-service-account_request\`._`,
+        ""
+      );
+    }
     return sections.join("\n");
   }
 };
 
 // ../connectors/src/connectors/google-analytics/tools/request.ts
 import { z } from "zod";
-var BASE_URL2 = "https://analyticsdata.googleapis.com/v1beta/";
+var BASE_URL2 = "https://analyticsdata.googleapis.com";
 var REQUEST_TIMEOUT_MS = 6e4;
 var inputSchema = z.object({
   toolUseIntent: z.string().optional().describe("Brief description of what you intend to accomplish with this tool call"),
   connectionId: z.string().describe("ID of the Google Analytics connection to use"),
-  propertyId: z.string().describe("GA4 property ID (e.g., '123456789')"),
   method: z.enum(["GET", "POST"]).describe("HTTP method"),
-  path: z.string().describe("API path (e.g., 'properties/{propertyId}:runReport'). {propertyId} is replaced with the propertyId parameter."),
+  path: z.string().describe("Full request path including the API version prefix, appended to https://analyticsdata.googleapis.com. Use the same form as the GA4 Data API reference, e.g., '/v1beta/properties/123456789:runReport'."),
   body: z.record(z.string(), z.unknown()).optional().describe("POST request body (JSON)")
 });
 var outputSchema = z.discriminatedUnion("success", [
@@ -820,11 +1229,10 @@ var outputSchema = z.discriminatedUnion("success", [
 var requestTool = new ConnectorTool({
   name: "request",
   description: `Send authenticated requests to the Google Analytics Data API.
-Authentication is handled automatically using a service account.
-{propertyId} in the path is automatically replaced with the propertyId parameter.`,
+Authentication is handled automatically using a service account.`,
   inputSchema,
   outputSchema,
-  async execute({ connectionId, propertyId, method, path: path2, body }, connections) {
+  async execute({ connectionId, method, path: path2, body }, connections) {
     const connection2 = connections.find((c) => c.id === connectionId);
     if (!connection2) {
       return { success: false, error: `Connection ${connectionId} not found` };
@@ -844,8 +1252,7 @@ Authentication is handled automatically using a service account.
       if (!token) {
         return { success: false, error: "Failed to obtain access token" };
       }
-      const resolvedPath = path2.replace(/\{propertyId\}/g, propertyId);
-      const url = `${BASE_URL2}${resolvedPath}`;
+      const url = `${BASE_URL2}${path2}`;
       const controller = new AbortController();
       const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
       try {
@@ -892,18 +1299,20 @@ var googleAnalyticsConnector = new ConnectorPlugin({
   systemPrompt: {
     en: `### Tools
 
-- \`google-analytics-service-account_request\`: The only way to call the GA4 Data API. Use it to fetch metadata, run reports, or run realtime reports. Requires a \`propertyId\` parameter. See the GA4 Data API Reference below for available endpoints and request bodies.
+- \`connector_google-analytics-service-account_request\`: The only way to call the GA4 Data API. Use it to fetch metadata, run reports, or run realtime reports. See the GA4 Data API Reference below for available endpoints and request bodies.
 
 ### Business Logic
 
 The business logic type for this connector is "typescript". Use the connector SDK in your handler. Do NOT read credentials from environment variables.
 
 SDK methods (client created via \`connection(connectionId)\`):
-- \`client.runReport(propertyId, request)\` \u2014 run a GA4 report
-- \`client.runRealtimeReport(propertyId, request)\` \u2014 run a realtime report
-- \`client.getMetadata(propertyId)\` \u2014 fetch available dimensions/metrics
+- \`client.runReport(request)\` \u2014 run a GA4 report
+- \`client.runRealtimeReport(request)\` \u2014 run a realtime report
+- \`client.getMetadata(request)\` \u2014 fetch available dimensions/metrics
 - \`client.request(path, init?)\` \u2014 low-level authenticated fetch
 
+**IMPORTANT**: You MUST always include \`propertyId\` in every SDK method call. The property ID is obtained during the setup flow. Without it, the request will fail.
+
 \`\`\`ts
 import type { Context } from "hono";
 import { connection } from "@squadbase/vite-server/connectors/google-analytics";
@@ -917,7 +1326,8 @@ export default async function handler(c: Context) {
     endDate?: string;
   }>();
 
-  const { rows } = await ga.runReport(propertyId, {
+  const { rows } = await ga.runReport({
+    propertyId,
     dateRanges: [{ startDate, endDate }],
     dimensions: [{ name: "date" }],
     metrics: [{ name: "activeUsers" }, { name: "sessions" }],
@@ -938,8 +1348,8 @@ export default async function handler(c: Context) {
 
 Common operations:
 
-- **Get metadata** (list available dimensions/metrics for a property): \`GET properties/{propertyId}/metadata\`
-- **Run report** (query analytics data): \`POST properties/{propertyId}:runReport\` with a body like:
+- **Get metadata** (list available dimensions/metrics for a property): \`GET /v1beta/properties/{propertyId}/metadata\`
+- **Run report** (query analytics data): \`POST /v1beta/properties/{propertyId}:runReport\` with a body like:
   \`\`\`json
   {
     "dateRanges": [{ "startDate": "7daysAgo", "endDate": "today" }],
@@ -948,7 +1358,7 @@ Common operations:
     "limit": 100
   }
   \`\`\`
-- **Run realtime report**: \`POST properties/{propertyId}:runRealtimeReport\`
+- **Run realtime report**: \`POST /v1beta/properties/{propertyId}:runRealtimeReport\`
 
 #### Common dimensions
 date, country, city, deviceCategory, browser, pagePath, pageTitle, sessionSource, sessionMedium, eventName
@@ -961,18 +1371,20 @@ activeUsers, sessions, screenPageViews, bounceRate, averageSessionDuration, conv
 - Relative: \`"today"\`, \`"yesterday"\`, \`"7daysAgo"\`, \`"30daysAgo"\``,
     ja: `### \u30C4\u30FC\u30EB
 
-- \`google-analytics-service-account_request\`: GA4 Data API\u3092\u547C\u3073\u51FA\u3059\u552F\u4E00\u306E\u624B\u6BB5\u3067\u3059\u3002\u30E1\u30BF\u30C7\u30FC\u30BF\u306E\u53D6\u5F97\u3001\u30EC\u30DD\u30FC\u30C8\u306E\u5B9F\u884C\u3001\u30EA\u30A2\u30EB\u30BF\u30A4\u30E0\u30EC\u30DD\u30FC\u30C8\u306E\u5B9F\u884C\u306B\u4F7F\u7528\u3057\u307E\u3059\u3002\`propertyId\` \u30D1\u30E9\u30E1\u30FC\u30BF\u30FC\u304C\u5FC5\u8981\u3067\u3059\u3002\u5229\u7528\u53EF\u80FD\u306A\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3068\u30EA\u30AF\u30A8\u30B9\u30C8\u30DC\u30C7\u30A3\u306F\u4E0B\u90E8\u306E\u300CGA4 Data API \u30EA\u30D5\u30A1\u30EC\u30F3\u30B9\u300D\u3092\u53C2\u7167\u3057\u3066\u304F\u3060\u3055\u3044\u3002
+- \`connector_google-analytics-service-account_request\`: GA4 Data API\u3092\u547C\u3073\u51FA\u3059\u552F\u4E00\u306E\u624B\u6BB5\u3067\u3059\u3002\u30E1\u30BF\u30C7\u30FC\u30BF\u306E\u53D6\u5F97\u3001\u30EC\u30DD\u30FC\u30C8\u306E\u5B9F\u884C\u3001\u30EA\u30A2\u30EB\u30BF\u30A4\u30E0\u30EC\u30DD\u30FC\u30C8\u306E\u5B9F\u884C\u306B\u4F7F\u7528\u3057\u307E\u3059\u3002\u5229\u7528\u53EF\u80FD\u306A\u30A8\u30F3\u30C9\u30DD\u30A4\u30F3\u30C8\u3068\u30EA\u30AF\u30A8\u30B9\u30C8\u30DC\u30C7\u30A3\u306F\u4E0B\u90E8\u306E\u300CGA4 Data API \u30EA\u30D5\u30A1\u30EC\u30F3\u30B9\u300D\u3092\u53C2\u7167\u3057\u3066\u304F\u3060\u3055\u3044\u3002
 
 ### Business Logic
 
 \u3053\u306E\u30B3\u30CD\u30AF\u30BF\u306E\u30D3\u30B8\u30CD\u30B9\u30ED\u30B8\u30C3\u30AF\u30BF\u30A4\u30D7\u306F "typescript" \u3067\u3059\u3002\u30CF\u30F3\u30C9\u30E9\u5185\u3067\u306F\u30B3\u30CD\u30AF\u30BFSDK\u3092\u4F7F\u7528\u3057\u3066\u304F\u3060\u3055\u3044\u3002\u74B0\u5883\u5909\u6570\u304B\u3089\u8A8D\u8A3C\u60C5\u5831\u3092\u8AAD\u307F\u53D6\u3089\u306A\u3044\u3067\u304F\u3060\u3055\u3044\u3002
 
 SDK\u30E1\u30BD\u30C3\u30C9 (\`connection(connectionId)\` \u3067\u4F5C\u6210\u3057\u305F\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8):
-- \`client.runReport(propertyId, request)\` \u2014 GA4\u30EC\u30DD\u30FC\u30C8\u3092\u5B9F\u884C
-- \`client.runRealtimeReport(propertyId, request)\` \u2014 \u30EA\u30A2\u30EB\u30BF\u30A4\u30E0\u30EC\u30DD\u30FC\u30C8\u3092\u5B9F\u884C
-- \`client.getMetadata(propertyId)\` \u2014 \u5229\u7528\u53EF\u80FD\u306A\u30C7\u30A3\u30E1\u30F3\u30B7\u30E7\u30F3/\u30E1\u30C8\u30EA\u30AF\u30B9\u3092\u53D6\u5F97
+- \`client.runReport(request)\` \u2014 GA4\u30EC\u30DD\u30FC\u30C8\u3092\u5B9F\u884C
+- \`client.runRealtimeReport(request)\` \u2014 \u30EA\u30A2\u30EB\u30BF\u30A4\u30E0\u30EC\u30DD\u30FC\u30C8\u3092\u5B9F\u884C
+- \`client.getMetadata(request)\` \u2014 \u5229\u7528\u53EF\u80FD\u306A\u30C7\u30A3\u30E1\u30F3\u30B7\u30E7\u30F3/\u30E1\u30C8\u30EA\u30AF\u30B9\u3092\u53D6\u5F97
 - \`client.request(path, init?)\` \u2014 \u4F4E\u30EC\u30D9\u30EB\u306E\u8A8D\u8A3C\u4ED8\u304Dfetch
 
+**\u91CD\u8981**: \u3059\u3079\u3066\u306ESDK\u30E1\u30BD\u30C3\u30C9\u547C\u3073\u51FA\u3057\u306B\u306F\u5FC5\u305A \`propertyId\` \u3092\u542B\u3081\u3066\u304F\u3060\u3055\u3044\u3002\u30D7\u30ED\u30D1\u30C6\u30A3ID\u306F\u30BB\u30C3\u30C8\u30A2\u30C3\u30D7\u30D5\u30ED\u30FC\u3067\u53D6\u5F97\u3055\u308C\u307E\u3059\u3002\u6307\u5B9A\u3057\u306A\u3044\u3068\u30EA\u30AF\u30A8\u30B9\u30C8\u304C\u5931\u6557\u3057\u307E\u3059\u3002
+
 \`\`\`ts
 import type { Context } from "hono";
 import { connection } from "@squadbase/vite-server/connectors/google-analytics";
@@ -986,7 +1398,8 @@ export default async function handler(c: Context) {
     endDate?: string;
   }>();
 
-  const { rows } = await ga.runReport(propertyId, {
+  const { rows } = await ga.runReport({
+    propertyId,
     dateRanges: [{ startDate, endDate }],
     dimensions: [{ name: "date" }],
     metrics: [{ name: "activeUsers" }, { name: "sessions" }],
@@ -1007,8 +1420,8 @@ export default async function handler(c: Context) {
 
 \u4E3B\u306A\u64CD\u4F5C:
 
-- **\u30E1\u30BF\u30C7\u30FC\u30BF\u306E\u53D6\u5F97** (\u30D7\u30ED\u30D1\u30C6\u30A3\u3067\u5229\u7528\u53EF\u80FD\u306A\u30C7\u30A3\u30E1\u30F3\u30B7\u30E7\u30F3/\u30E1\u30C8\u30EA\u30AF\u30B9\u306E\u4E00\u89A7): \`GET properties/{propertyId}/metadata\`
-- **\u30EC\u30DD\u30FC\u30C8\u306E\u53D6\u5F97** (\u5206\u6790\u30C7\u30FC\u30BF\u306E\u30AF\u30A8\u30EA): \`POST properties/{propertyId}:runReport\`\u3001\u30DC\u30C7\u30A3\u4F8B:
+- **\u30E1\u30BF\u30C7\u30FC\u30BF\u306E\u53D6\u5F97** (\u30D7\u30ED\u30D1\u30C6\u30A3\u3067\u5229\u7528\u53EF\u80FD\u306A\u30C7\u30A3\u30E1\u30F3\u30B7\u30E7\u30F3/\u30E1\u30C8\u30EA\u30AF\u30B9\u306E\u4E00\u89A7): \`GET /v1beta/properties/{propertyId}/metadata\`
+- **\u30EC\u30DD\u30FC\u30C8\u306E\u53D6\u5F97** (\u5206\u6790\u30C7\u30FC\u30BF\u306E\u30AF\u30A8\u30EA): \`POST /v1beta/properties/{propertyId}:runReport\`\u3001\u30DC\u30C7\u30A3\u4F8B:
   \`\`\`json
   {
     "dateRanges": [{ "startDate": "7daysAgo", "endDate": "today" }],
@@ -1017,7 +1430,7 @@ export default async function handler(c: Context) {
     "limit": 100
   }
   \`\`\`
-- **\u30EA\u30A2\u30EB\u30BF\u30A4\u30E0\u30EC\u30DD\u30FC\u30C8**: \`POST properties/{propertyId}:runRealtimeReport\`
+- **\u30EA\u30A2\u30EB\u30BF\u30A4\u30E0\u30EC\u30DD\u30FC\u30C8**: \`POST /v1beta/properties/{propertyId}:runRealtimeReport\`
 
 #### \u4E3B\u8981\u306A\u30C7\u30A3\u30E1\u30F3\u30B7\u30E7\u30F3
 date, country, city, deviceCategory, browser, pagePath, pageTitle, sessionSource, sessionMedium, eventName
@@ -1039,8 +1452,22 @@ activeUsers, sessions, screenPageViews, bounceRate, averageSessionDuration, conv
         error: "google-analytics: missing service account key"
       };
     }
+    const propertyId = params[parameters.propertyId.slug];
+    if (!propertyId) {
+      try {
+        const sa = decodeServiceAccount(keyJsonBase64);
+        await getAccessToken(sa);
+        return { success: true };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { success: false, error: msg };
+      }
+    }
     try {
-      const res = await dataFetch(params, `/metadata`);
+      const res = await dataFetch(
+        params,
+        `/properties/${propertyId}/metadata`
+      );
       if (!res.ok) {
         const body = await res.text().catch(() => res.statusText);
         return {