@koda-sl/baker-cli 0.573.0 → 0.574.0

package/dist/query-ALRSR5OF.js

@@ -0,0 +1,236 @@
+import {
+  resolvePropertyId
+} from "./chunk-2ZKQNMK2.js";
+import {
+  buildQueryCacheKey,
+  cacheGet,
+  cacheSet,
+  getQueryTtl,
+  handleConnectionError,
+  isNotConnectedError,
+  toCsvRow,
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-VJUVTMHY.js";
+import {
+  ApiError,
+  apiPost
+} from "./chunk-JCFZ7ECN.js";
+import "./chunk-OFSUVUXT.js";
+import "./chunk-OMLZ35HJ.js";
+import {
+  registerSchema
+} from "./chunk-NXNOXZGB.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/ga4/query.ts
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { defineCommand } from "citty";
+
+// src/commands/ga4/presets.ts
+var GA4_PRESETS = [
+  {
+    name: "tracking-health",
+    description: "Compare GA4 sessions to GAds clicks \u2014 flag >20% discrepancy",
+    playbook: "[07] Discrepancy Check"
+  },
+  {
+    name: "lp-performance",
+    description: "Landing page UX diagnostic \u2014 flag duration <10s as message mismatch",
+    playbook: "[06] LP Diagnostic"
+  },
+  {
+    name: "traffic-quality",
+    description: "Warm traffic trap \u2014 flag >40% returning user conversions",
+    playbook: "[06] Warm Traffic Trap"
+  },
+  {
+    name: "funnel-leakage",
+    description: "Funnel drop-off analysis between form events",
+    playbook: "[06] Funnel Analysis"
+  },
+  {
+    name: "first-touch",
+    description: "First-touch attribution \u2014 true acquisition value of channels",
+    playbook: "First-Touch Attribution"
+  },
+  {
+    name: "traffic-overview",
+    description: "General traffic trends by date and source",
+    playbook: "General"
+  }
+];
+
+// src/commands/ga4/query.ts
+registerSchema({
+  command: "ga4.query",
+  description: "Run GA4 Data API reports. Use --preset for playbook-aligned queries (primary usage) or --dimensions/--metrics for free-form queries.",
+  args: {
+    "property-id": { type: "string", description: "GA4 property ID (auto-resolved if not provided)", required: false },
+    preset: {
+      type: "string",
+      description: "Named preset (tracking-health, lp-performance, traffic-quality, funnel-leakage, first-touch, traffic-overview)",
+      required: false
+    },
+    dimensions: { type: "string", description: "Comma-separated dimension names (escape hatch)", required: false },
+    metrics: { type: "string", description: "Comma-separated metric names (escape hatch)", required: false },
+    days: { type: "string", description: "Lookback window in days (default: 30)", required: false },
+    "start-date": {
+      type: "string",
+      description: "Explicit start date (YYYY-MM-DD or GA4 relative like '30daysAgo')",
+      required: false
+    },
+    "end-date": { type: "string", description: "Explicit end date (YYYY-MM-DD or 'yesterday')", required: false },
+    limit: { type: "string", description: "Max rows (default: 1000)", required: false },
+    "list-presets": { type: "boolean", description: "List available presets", required: false },
+    out: { type: "string", description: "Write data to file (.csv, .jsonl, .json)", required: false },
+    append: { type: "boolean", description: "Append to existing file", required: false },
+    output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false }
+  }
+});
+function extractFields(rows) {
+  const first = rows[0];
+  return first ? Object.keys(first) : [];
+}
+function writeRowsToFile(filePath, rows, append) {
+  const fields = extractFields(rows);
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  if (ext === "csv") {
+    if (!append || !existsSync(filePath)) {
+      writeFileSync(filePath, `${toCsvRow(fields)}
+`, "utf-8");
+    }
+    const csvRows = rows.map((row) => toCsvRow(fields.map((f) => String(row[f] ?? ""))));
+    appendFileSync(filePath, `${csvRows.join("\n")}
+`, "utf-8");
+  } else if (ext === "jsonl") {
+    const lines = rows.map((row) => JSON.stringify(row));
+    const content = `${lines.join("\n")}
+`;
+    if (append && existsSync(filePath)) {
+      appendFileSync(filePath, content, "utf-8");
+    } else {
+      writeFileSync(filePath, content, "utf-8");
+    }
+  } else if (append && existsSync(filePath)) {
+    const existing = JSON.parse(readFileSync(filePath, "utf-8"));
+    writeFileSync(filePath, JSON.stringify([...existing, ...rows], null, 2), "utf-8");
+  } else {
+    writeFileSync(filePath, JSON.stringify(rows, null, 2), "utf-8");
+  }
+}
+function outputRows(rows, args, response, cached) {
+  if (args.out) {
+    const filePath = resolve(args.out);
+    writeRowsToFile(filePath, rows, !!args.append);
+    writeJsonEnvelope({ ok: true, file: filePath, rows: rows.length, ...cached && { cached: true } });
+    return;
+  }
+  const format = args.output || "json";
+  if (format !== "json") {
+    writeAdsOutput(rows, format);
+    return;
+  }
+  writeJsonEnvelope({ ...response, ...cached && { cached: true } });
+}
+function buildRequestBody(args, propertyId, useCache) {
+  const body = { propertyId };
+  if (args.preset) body.preset = args.preset;
+  if (args.dimensions) body.dimensions = args.dimensions.split(",").map((d) => d.trim());
+  if (args.metrics) body.metrics = args.metrics.split(",").map((m) => m.trim());
+  if (args.days) body.days = Number(args.days);
+  if (args["start-date"]) body.startDate = args["start-date"];
+  if (args["end-date"]) body.endDate = args["end-date"];
+  if (args.limit) body.limit = Number(args.limit);
+  if (!useCache) body.skipCache = true;
+  return body;
+}
+function handleError(err) {
+  if (err instanceof ApiError) {
+    if (isNotConnectedError(err.code, err.message)) {
+      handleConnectionError("ga4", err.message);
+    }
+    writeJsonEnvelope({ ok: false, error: { code: err.code, message: err.message } });
+    process.exit(1);
+  }
+  writeJsonEnvelope({
+    ok: false,
+    error: { code: "NETWORK_ERROR", message: err instanceof Error ? err.message : "Unexpected error" }
+  });
+  process.exit(1);
+}
+var queryCommand = defineCommand({
+  meta: {
+    name: "query",
+    description: `Run GA4 Data API reports. Preset-first with free-form escape hatch.
+
+Presets (primary usage):
+  baker ga4 query --preset tracking-health
+  baker ga4 query --preset lp-performance --days 14
+  baker ga4 query --list-presets
+
+Free-form (escape hatch):
+  baker ga4 query --dimensions "date,sessionSourceMedium" --metrics "sessions,conversions"
+  baker ga4 query --metrics "eventCount" --dimensions "eventName" --days 7`
+  },
+  args: {
+    "property-id": { type: "string", description: "GA4 property ID", required: false },
+    preset: { type: "string", description: "Named preset", required: false },
+    dimensions: { type: "string", description: "Comma-separated dimensions", required: false },
+    metrics: { type: "string", description: "Comma-separated metrics", required: false },
+    days: { type: "string", description: "Lookback days (default: 30)", required: false },
+    "start-date": { type: "string", description: "Start date override", required: false },
+    "end-date": { type: "string", description: "End date override", required: false },
+    limit: { type: "string", description: "Max rows (default: 1000)", required: false },
+    "list-presets": { type: "boolean", description: "List presets", required: false },
+    out: { type: "string", description: "Output file path", required: false },
+    append: { type: "boolean", description: "Append to file", required: false },
+    output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false }
+  },
+  run: async ({ args }) => {
+    if (args["list-presets"]) {
+      writeJsonEnvelope({
+        ok: true,
+        data: GA4_PRESETS.map((p) => ({ name: p.name, description: p.description, playbook: p.playbook }))
+      });
+      return;
+    }
+    if (!args.preset && !args.metrics) {
+      writeJsonEnvelope({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: "Provide --preset or --metrics. Run --list-presets to see options."
+        }
+      });
+      process.exit(1);
+    }
+    const propertyId = await resolvePropertyId(args);
+    const useCache = !args["no-cache"];
+    const body = buildRequestBody(args, propertyId, useCache);
+    const cacheKey = buildQueryCacheKey(propertyId, JSON.stringify(body));
+    if (useCache) {
+      const cached = cacheGet("ga4-queries", cacheKey);
+      if (cached) {
+        outputRows(cached.data.data ?? [], args, cached.data, true);
+        return;
+      }
+    }
+    try {
+      const response = await apiPost("/api/ga4/query", body);
+      if (useCache) {
+        cacheSet("ga4-queries", cacheKey, response, getQueryTtl(JSON.stringify(body)));
+      }
+      outputRows(response.data ?? [], args, response, false);
+    } catch (err) {
+      handleError(err);
+    }
+  }
+});
+export {
+  queryCommand
+};
+//# sourceMappingURL=query-ALRSR5OF.js.map

package/dist/query-NYH5PMQF.js

@@ -0,0 +1,62 @@
+import {
+  buildFileSummary,
+  buildQueryEnvelope,
+  completenessWarnings,
+  effectiveRowLimit,
+  keywordServingOptions,
+  missingFieldWarnings,
+  missingFieldWarningsFor,
+  outputResults,
+  pageCacheKey,
+  parseQueryLimit,
+  parseSelectedFields,
+  queryCommand,
+  queryPageSize,
+  resolveGaqlInput,
+  resultColumns,
+  runQuery,
+  servingScopeWarnings,
+  shouldReadCache,
+  summariseWarnings,
+  unobservedFields,
+  unobservedSelectedFields,
+  unwrittenColumnWarnings,
+  warningLines
+} from "./chunk-QENSBNRJ.js";
+import "./chunk-Y2FAUFWK.js";
+import "./chunk-JQDYH5XP.js";
+import "./chunk-FTP6NDOU.js";
+import "./chunk-BMMXYR7A.js";
+import "./chunk-VJUVTMHY.js";
+import "./chunk-XHWHBGKX.js";
+import "./chunk-JCFZ7ECN.js";
+import "./chunk-OFSUVUXT.js";
+import "./chunk-OMLZ35HJ.js";
+import "./chunk-NXNOXZGB.js";
+import "./chunk-YQSBHWOI.js";
+export {
+  buildFileSummary,
+  buildQueryEnvelope,
+  completenessWarnings,
+  effectiveRowLimit,
+  keywordServingOptions,
+  missingFieldWarnings,
+  missingFieldWarningsFor,
+  outputResults,
+  pageCacheKey,
+  parseQueryLimit,
+  parseSelectedFields,
+  queryCommand,
+  queryPageSize,
+  resolveGaqlInput,
+  resultColumns,
+  runQuery,
+  servingScopeWarnings,
+  shouldReadCache,
+  summariseWarnings,
+  unobservedFields,
+  unobservedSelectedFields,
+  unwrittenColumnWarnings,
+  warningLines
+};
+//# sourceMappingURL=query-NYH5PMQF.js.map

package/dist/query-ZGGHOYOH.js

@@ -0,0 +1,231 @@
+import {
+  handleGscSiteError,
+  resolveSiteUrl
+} from "./chunk-MWPM6HNV.js";
+import {
+  buildQueryCacheKey,
+  cacheGet,
+  cacheSet,
+  getQueryTtl,
+  toCsvRow,
+  writeAdsOutput,
+  writeJsonEnvelope
+} from "./chunk-VJUVTMHY.js";
+import {
+  apiPost
+} from "./chunk-JCFZ7ECN.js";
+import "./chunk-OFSUVUXT.js";
+import "./chunk-OMLZ35HJ.js";
+import {
+  registerSchema
+} from "./chunk-NXNOXZGB.js";
+import "./chunk-YQSBHWOI.js";
+
+// src/commands/gsc/query.ts
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+import { defineCommand } from "citty";
+
+// src/commands/gsc/presets.ts
+var GSC_PRESETS = [
+  {
+    name: "cannibalization",
+    description: "PPC-SEO arbitrage \u2014 find queries ranking #1-2 organically where you also pay for ads",
+    playbook: "[05] PPC-SEO Arbitrage"
+  },
+  {
+    name: "missed-revenue",
+    description: "High-impression queries with no PPC coverage (position > 10)",
+    playbook: "[05] Opportunity Finder"
+  },
+  {
+    name: "brand-halo",
+    description: "Brand search volume trends \u2014 proves upper-funnel awareness lift",
+    playbook: "[21] YouTube/DG ROI",
+    requiresBrand: true
+  },
+  {
+    name: "negative-keywords",
+    description: "Discover negative keyword candidates (login, support, cancel queries)",
+    playbook: "Negative Keyword Discovery"
+  },
+  {
+    name: "top-pages",
+    description: "Top performing pages by clicks",
+    playbook: "General"
+  },
+  {
+    name: "top-queries",
+    description: "Top search queries by clicks",
+    playbook: "General"
+  }
+];
+
+// src/commands/gsc/query.ts
+registerSchema({
+  command: "gsc.query",
+  description: "Run GSC Search Analytics queries. Use --preset for playbook-aligned queries (primary usage) or --dimensions for free-form queries.",
+  args: {
+    "site-url": { type: "string", description: "Site URL (auto-resolved if not provided)", required: false },
+    preset: {
+      type: "string",
+      description: "Named preset (cannibalization, missed-revenue, brand-halo, negative-keywords, top-pages, top-queries)",
+      required: false
+    },
+    brand: { type: "string", description: "Brand name (required for brand-halo preset)", required: false },
+    dimensions: {
+      type: "string",
+      description: "Comma-separated dimensions (escape hatch: query, page, country, device, date)",
+      required: false
+    },
+    days: { type: "string", description: "Lookback window in days (default: 28)", required: false },
+    "start-date": { type: "string", description: "Explicit start date (YYYY-MM-DD)", required: false },
+    "end-date": { type: "string", description: "Explicit end date (YYYY-MM-DD)", required: false },
+    "row-limit": { type: "string", description: "Max rows (default: 1000, max: 25000)", required: false },
+    type: { type: "string", description: "Search type: web|image|video|news|discover (default: web)", required: false },
+    filter: { type: "string", description: "Dimension filter groups as JSON string", required: false },
+    "list-presets": { type: "boolean", description: "List available presets", required: false },
+    out: { type: "string", description: "Write data to file (.csv, .jsonl, .json)", required: false },
+    append: { type: "boolean", description: "Append to existing file", required: false },
+    output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false }
+  }
+});
+function extractFields(rows) {
+  const first = rows[0];
+  return first ? Object.keys(first) : [];
+}
+function writeRowsToFile(filePath, rows, append) {
+  const fields = extractFields(rows);
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  if (ext === "csv") {
+    if (!append || !existsSync(filePath)) {
+      writeFileSync(filePath, `${toCsvRow(fields)}
+`, "utf-8");
+    }
+    const csvRows = rows.map((row) => toCsvRow(fields.map((f) => String(row[f] ?? ""))));
+    appendFileSync(filePath, `${csvRows.join("\n")}
+`, "utf-8");
+  } else if (ext === "jsonl") {
+    const content = `${rows.map((row) => JSON.stringify(row)).join("\n")}
+`;
+    if (append && existsSync(filePath)) {
+      appendFileSync(filePath, content, "utf-8");
+    } else {
+      writeFileSync(filePath, content, "utf-8");
+    }
+  } else if (append && existsSync(filePath)) {
+    const existing = JSON.parse(readFileSync(filePath, "utf-8"));
+    writeFileSync(filePath, JSON.stringify([...existing, ...rows], null, 2), "utf-8");
+  } else {
+    writeFileSync(filePath, JSON.stringify(rows, null, 2), "utf-8");
+  }
+}
+function outputRows(rows, args, response, cached) {
+  if (args.out) {
+    const filePath = resolve(args.out);
+    writeRowsToFile(filePath, rows, !!args.append);
+    writeJsonEnvelope({ ok: true, file: filePath, rows: rows.length, ...cached && { cached: true } });
+    return;
+  }
+  const format = args.output || "json";
+  if (format !== "json") {
+    writeAdsOutput(rows, format);
+    return;
+  }
+  writeJsonEnvelope({ ...response, ...cached && { cached: true } });
+}
+function buildRequestBody(args, siteUrl, useCache) {
+  const body = { siteUrl };
+  if (args.preset) body.preset = args.preset;
+  if (args.brand) body.brand = args.brand;
+  if (args.dimensions) body.dimensions = args.dimensions.split(",").map((d) => d.trim());
+  if (args.days) body.days = Number(args.days);
+  if (args["start-date"]) body.startDate = args["start-date"];
+  if (args["end-date"]) body.endDate = args["end-date"];
+  if (args["row-limit"]) body.rowLimit = Number(args["row-limit"]);
+  if (args.type) body.type = args.type;
+  if (args.filter) body.filter = args.filter;
+  if (!useCache) body.skipCache = true;
+  return body;
+}
+var queryCommand = defineCommand({
+  meta: {
+    name: "query",
+    description: `Run GSC Search Analytics queries. Preset-first with free-form escape hatch.
+
+Presets (primary usage):
+  baker gsc query --preset cannibalization
+  baker gsc query --preset brand-halo --brand "Acme" --days 90
+  baker gsc query --list-presets
+
+Free-form (escape hatch):
+  baker gsc query --dimensions "query,page" --days 28
+  baker gsc query --dimensions "query" --row-limit 25000 --out keywords.csv`
+  },
+  args: {
+    "site-url": { type: "string", description: "Site URL", required: false },
+    preset: { type: "string", description: "Named preset", required: false },
+    brand: { type: "string", description: "Brand name for brand-halo preset", required: false },
+    dimensions: { type: "string", description: "Comma-separated dimensions", required: false },
+    days: { type: "string", description: "Lookback days (default: 28)", required: false },
+    "start-date": { type: "string", description: "Start date override", required: false },
+    "end-date": { type: "string", description: "End date override", required: false },
+    "row-limit": { type: "string", description: "Max rows (default: 1000)", required: false },
+    type: { type: "string", description: "Search type (default: web)", required: false },
+    filter: { type: "string", description: "Filter JSON", required: false },
+    "list-presets": { type: "boolean", description: "List presets", required: false },
+    out: { type: "string", description: "Output file path", required: false },
+    append: { type: "boolean", description: "Append to file", required: false },
+    output: { type: "string", description: "Format: json|csv|jsonl|md", required: false, default: "json" },
+    "no-cache": { type: "boolean", description: "Skip cache", required: false }
+  },
+  run: async ({ args }) => {
+    if (args["list-presets"]) {
+      writeJsonEnvelope({
+        ok: true,
+        data: GSC_PRESETS.map((p) => ({
+          name: p.name,
+          description: p.description,
+          playbook: p.playbook,
+          ...p.requiresBrand && { requiresBrand: true }
+        }))
+      });
+      return;
+    }
+    if (!args.preset && !args.dimensions) {
+      writeJsonEnvelope({
+        ok: false,
+        error: {
+          code: "VALIDATION_ERROR",
+          message: "Provide --preset or --dimensions. Run --list-presets to see options."
+        }
+      });
+      process.exit(1);
+    }
+    const siteUrl = await resolveSiteUrl(args);
+    const useCache = !args["no-cache"];
+    const body = buildRequestBody(args, siteUrl, useCache);
+    const cacheKey = buildQueryCacheKey(siteUrl, JSON.stringify(body));
+    if (useCache) {
+      const cached = cacheGet("gsc-queries", cacheKey);
+      if (cached) {
+        outputRows(cached.data.data ?? [], args, cached.data, true);
+        return;
+      }
+    }
+    try {
+      const response = await apiPost("/api/gsc/query", body);
+      if (useCache) {
+        cacheSet("gsc-queries", cacheKey, response, getQueryTtl(JSON.stringify(body)));
+      }
+      outputRows(response.data ?? [], args, response, false);
+    } catch (err) {
+      await handleGscSiteError(err, siteUrl);
+    }
+  }
+});
+export {
+  queryCommand
+};
+//# sourceMappingURL=query-ZGGHOYOH.js.map

package/dist/questionnaire-4AJFPLM2.js

@@ -0,0 +1,94 @@
+import {
+  questionnaireErrorEnvelope
+} from "./chunk-RSABCQLI.js";
+import "./chunk-PILLZPNC.js";
+import "./chunk-NKQWDEB7.js";
+import {
+  writeJsonEnvelope
+} from "./chunk-VJUVTMHY.js";
+import "./chunk-G4FG5EQO.js";
+import {
+  apiPost
+} from "./chunk-JCFZ7ECN.js";
+import "./chunk-OFSUVUXT.js";
+import "./chunk-OMLZ35HJ.js";
+import {
+  registerSchema
+} from "./chunk-NXNOXZGB.js";
+import "./chunk-YQSBHWOI.js";
+
+// ../api/src/analytics/questionnaire.ts
+import { z } from "zod";
+var questionnaireObservationSchema = z.object({
+  attemptId: z.string().min(1).max(100),
+  version: z.string().min(1).max(100),
+  stepId: z.string().max(100),
+  sequence: z.number().int().positive(),
+  phase: z.enum(["start", "view", "complete", "skip", "finish"]),
+  timestamp: z.number().finite()
+}).refine(
+  (event) => ["start", "finish"].includes(event.phase) || event.stepId.length > 0,
+  "A question event needs its stable step id"
+);
+var questionnaireRequestSchema = z.object({
+  eventName: z.string().min(1).max(100).default("questionnaire_step"),
+  days: z.number().int().min(1).max(90).default(7),
+  inactivityMinutes: z.number().int().min(5).max(1440).default(30)
+});
+var stepSchema = z.object({
+  version: z.string(),
+  stepId: z.string(),
+  reached: z.number(),
+  completed: z.number(),
+  skipped: z.number(),
+  abandoned: z.number(),
+  pending: z.number(),
+  incomplete: z.number()
+});
+var questionnaireResponseSchema = z.object({
+  ok: z.literal(true),
+  data: z.object({
+    steps: z.array(stepSchema),
+    attempts: z.number(),
+    excludedAttempts: z.number(),
+    unmeasuredEvents: z.number(),
+    observationEndsAt: z.string(),
+    inactivityMinutes: z.number()
+  }),
+  hints: z.array(z.string())
+});
+
+// src/commands/analytics/questionnaire.ts
+import { defineCommand } from "citty";
+var description = "Question-level drop-off from the external questionnaire contract: start, viewed, completed, skipped and finished per attempt, version and sequence. Reports actual reached questions and the last unanswered one after inactivity; deduplicates repeated visits. Refuses a truncated feed (maximum 600 events), so narrow --days if needed. No events is not proof of zero abandonment. The contract is in analytics.md.";
+var args = {
+  name: { type: "string", description: "Event name (default questionnaire_step)", required: false },
+  days: { type: "string", description: "Observation window in days (default 7, maximum 90)", required: false },
+  inactivity: {
+    type: "string",
+    description: "Minutes without an event before abandonment (default 30)",
+    required: false
+  }
+};
+registerSchema({ command: "analytics.questionnaire", description, args });
+var questionnaireCommand = defineCommand({
+  meta: { name: "questionnaire", description },
+  args,
+  run: async ({ args: args2 }) => {
+    try {
+      const body = questionnaireRequestSchema.parse({
+        ...args2.name ? { eventName: args2.name } : {},
+        ...args2.days ? { days: Number(args2.days) } : {},
+        ...args2.inactivity ? { inactivityMinutes: Number(args2.inactivity) } : {}
+      });
+      writeJsonEnvelope(questionnaireResponseSchema.parse(await apiPost("/api/analytics/questionnaire", body)));
+    } catch (error) {
+      writeJsonEnvelope({ ok: false, error: questionnaireErrorEnvelope(error) });
+      process.exitCode = 1;
+    }
+  }
+});
+export {
+  questionnaireCommand
+};
+//# sourceMappingURL=questionnaire-4AJFPLM2.js.map