@agentsean/google 1.0.0

package/dist/waterfall.js

@@ -0,0 +1,167 @@
+import { randomUUID } from "node:crypto";
+import { and, eq } from "drizzle-orm";
+import { ga4Connections, ga4Daily, gscDaily, gscQueryDaily, reconciliationWaterfall, } from "@agentsean/db";
+import { DISCREPANCY_CAUSES, EU_GA4_INVISIBLE_HIGH, EU_GA4_INVISIBLE_LOW, GSC_ANONYMIZED_SHARE, isEuTimeZone, } from "./causes.js";
+import { computeResidual } from "./reconcile.js";
+function clamp01(n) {
+    if (!Number.isFinite(n))
+        return 0;
+    if (n < 0)
+        return 0;
+    if (n > 1)
+        return 1;
+    return n;
+}
+/**
+ * Named 17-cause waterfall. It explains the residual; it does not force
+ * GA4 and GSC to match. The leftover is the honest number.
+ */
+export function buildWaterfall(input) {
+    const gscClicks = Math.max(0, input.gscClicks);
+    const queryClicks = Math.max(0, input.queryDimensionClicks);
+    const ga4 = Math.max(0, input.ga4OrganicSessions);
+    const anonymized = gscClicks > 0 ? clamp01(1 - queryClicks / gscClicks) : GSC_ANONYMIZED_SHARE;
+    const eu = isEuTimeZone(input.timeZone ?? null);
+    const euShare = eu ? (EU_GA4_INVISIBLE_LOW + EU_GA4_INVISIBLE_HIGH) / 2 : null;
+    const residualRow = computeResidual(gscClicks, ga4);
+    const windowDays = daySpan(input.windowStart, input.windowEnd);
+    const steps = DISCREPANCY_CAUSES.map((cause) => {
+        switch (cause.code) {
+            case "GSC_ANONYMIZED_QUERY":
+                return step(cause, true, anonymized, `Query view covers ${pct(1 - anonymized)} of clicks.`);
+            case "GA4_CONSENT_DENIED":
+                return step(cause, eu, euShare, eu
+                    ? `EU/UK property: ${pct(EU_GA4_INVISIBLE_LOW)}–${pct(EU_GA4_INVISIBLE_HIGH)} of organic is permanently invisible in GA4.`
+                    : "Not flagged as an EU property timezone.");
+            case "DEF_TIMEZONE":
+                return step(cause, true, windowDays >= 7 ? 0 : null, windowDays >= 7
+                    ? "Compared on a ≥7-day window; single-day timezone skew collapses."
+                    : "Window shorter than 7 days — timezone skew can dominate a single day.");
+            case "GA4_SAMPLING":
+                return step(cause, Boolean(input.sampled), null, input.sampled
+                    ? "Sampled GA4 number — do not report without a warning."
+                    : "No sampling flag.");
+            case "GA4_THRESHOLDING":
+                return step(cause, Boolean(input.thresholded), null, input.thresholded
+                    ? "Thresholded GA4 number — hard gate."
+                    : "No thresholding flag.");
+            default:
+                return step(cause, cause.alwaysPresent, null, cause.notes);
+        }
+    });
+    const notes = [
+        residualRow.notes,
+        `Anonymized GSC queries ≈ ${pct(anonymized)} of clicks (industry 46.8%).`,
+        eu
+            ? `EU property: ${pct(EU_GA4_INVISIBLE_LOW)}–${pct(EU_GA4_INVISIBLE_HIGH)} of organic traffic is permanently invisible in GA4.`
+            : "GA4 consent loss is the dominant extra gap on EU properties.",
+        "The residual is the leftover after naming every structural cause. It is not a bug to fix.",
+    ].join(" ");
+    return {
+        windowStart: input.windowStart,
+        windowEnd: input.windowEnd,
+        gscClicks,
+        queryDimensionClicks: queryClicks,
+        ga4OrganicSessions: ga4,
+        residual: residualRow.residual,
+        residualPct: residualRow.residualPct,
+        anonymizedQueryShare: anonymized,
+        euInvisibleShare: euShare,
+        euProperty: eu,
+        steps,
+        notes,
+    };
+}
+function step(cause, applies, estimatedShare, detail) {
+    return Object.assign({}, cause, { applies, estimatedShare, detail });
+}
+function pct(n) {
+    return `${Math.round(n * 1000) / 10}%`;
+}
+function daySpan(start, end) {
+    const a = Date.parse(`${start}T00:00:00Z`);
+    const b = Date.parse(`${end}T00:00:00Z`);
+    if (!Number.isFinite(a) || !Number.isFinite(b))
+        return 0;
+    return Math.round((b - a) / 86_400_000) + 1;
+}
+export function waterfallFromSite(db, siteId, windowStart, windowEnd) {
+    const gsc = db.select().from(gscDaily).where(eq(gscDaily.siteId, siteId)).all();
+    const queries = db
+        .select()
+        .from(gscQueryDaily)
+        .where(eq(gscQueryDaily.siteId, siteId))
+        .all();
+    const ga4 = db.select().from(ga4Daily).where(eq(ga4Daily.siteId, siteId)).all();
+    const conn = db
+        .select()
+        .from(ga4Connections)
+        .where(eq(ga4Connections.siteId, siteId))
+        .get();
+    let gscClicks = 0;
+    for (const row of gsc) {
+        if (row.searchType !== "web")
+            continue;
+        if (row.date < windowStart || row.date > windowEnd)
+            continue;
+        gscClicks += row.clicks;
+    }
+    let queryClicks = 0;
+    for (const row of queries) {
+        if (row.searchType !== "web")
+            continue;
+        if (row.date < windowStart || row.date > windowEnd)
+            continue;
+        queryClicks += row.clicks;
+    }
+    let ga4Sessions = 0;
+    for (const row of ga4) {
+        if (row.date < windowStart || row.date > windowEnd)
+            continue;
+        ga4Sessions += row.organicSessions;
+    }
+    return buildWaterfall({
+        gscClicks,
+        queryDimensionClicks: queryClicks,
+        ga4OrganicSessions: ga4Sessions,
+        windowStart,
+        windowEnd,
+        timeZone: conn?.timeZone ?? null,
+    });
+}
+export function persistWaterfall(db, siteId, result, now = new Date()) {
+    const existing = db
+        .select()
+        .from(reconciliationWaterfall)
+        .where(and(eq(reconciliationWaterfall.siteId, siteId), eq(reconciliationWaterfall.windowStart, result.windowStart), eq(reconciliationWaterfall.windowEnd, result.windowEnd)))
+        .get();
+    const values = {
+        date: result.windowEnd,
+        gscClicks: result.gscClicks,
+        ga4OrganicSessions: result.ga4OrganicSessions,
+        residual: result.residual,
+        residualPct: result.residualPct,
+        causesJson: JSON.stringify(result.steps),
+        anonymizedQueryShare: result.anonymizedQueryShare,
+        euInvisibleShare: result.euInvisibleShare,
+        notes: result.notes,
+        createdAt: now.toISOString(),
+    };
+    if (existing) {
+        db.update(reconciliationWaterfall)
+            .set(values)
+            .where(eq(reconciliationWaterfall.id, existing.id))
+            .run();
+        return;
+    }
+    db.insert(reconciliationWaterfall)
+        .values({
+        id: randomUUID(),
+        siteId,
+        windowStart: result.windowStart,
+        windowEnd: result.windowEnd,
+        ...values,
+    })
+        .run();
+}
+//# sourceMappingURL=waterfall.js.map

package/dist/waterfall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"waterfall.js","sourceRoot":"","sources":["../src/waterfall.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEtC,OAAO,EACL,cAAc,EACd,QAAQ,EACR,QAAQ,EACR,aAAa,EACb,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,GAEb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAkCjD,SAAS,OAAO,CAAC,CAAS;IACxB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACpB,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,oBAAoB,CAAC,CAAC;IAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAClD,MAAM,UAAU,GACd,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC;IAC9E,MAAM,EAAE,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,oBAAoB,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/E,MAAM,WAAW,GAAG,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAE/D,MAAM,KAAK,GAAoB,kBAAkB,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9D,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,sBAAsB;gBACzB,OAAO,IAAI,CACT,KAAK,EACL,IAAI,EACJ,UAAU,EACV,qBAAqB,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,aAAa,CACtD,CAAC;YACJ,KAAK,oBAAoB;gBACvB,OAAO,IAAI,CACT,KAAK,EACL,EAAE,EACF,OAAO,EACP,EAAE;oBACA,CAAC,CAAC,mBAAmB,GAAG,CAAC,oBAAoB,CAAC,IAAI,GAAG,CAAC,qBAAqB,CAAC,8CAA8C;oBAC1H,CAAC,CAAC,yCAAyC,CAC9C,CAAC;YACJ,KAAK,cAAc;gBACjB,OAAO,IAAI,CACT,KAAK,EACL,IAAI,EACJ,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAC1B,UAAU,IAAI,CAAC;oBACb,CAAC,CAAC,kEAAkE;oBACpE,CAAC,CAAC,uEAAuE,CAC5E,CAAC;YACJ,KAAK,cAAc;gBACjB,OAAO,IAAI,CACT,KAAK,EACL,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EACtB,IAAI,EACJ,KAAK,CAAC,OAAO;oBACX,CAAC,CAAC,uDAAuD;oBACzD,CAAC,CAAC,mBAAmB,CACxB,CAAC;YACJ,KAAK,kBAAkB;gBACrB,OAAO,IAAI,CACT,KAAK,EACL,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,EAC1B,IAAI,EACJ,KAAK,CAAC,WAAW;oBACf,CAAC,CAAC,qCAAqC;oBACvC,CAAC,CAAC,uBAAuB,CAC5B,CAAC;YACJ;gBACE,OAAO,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,aAAa,EAAE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG;QACZ,WAAW,CAAC,KAAK;QACjB,4BAA4B,GAAG,CAAC,UAAU,CAAC,8BAA8B;QACzE,EAAE;YACA,CAAC,CAAC,gBAAgB,GAAG,CAAC,oBAAoB,CAAC,IAAI,GAAG,CAAC,qBAAqB,CAAC,sDAAsD;YAC/H,CAAC,CAAC,8DAA8D;QAClE,2FAA2F;KAC5F,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEZ,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,SAAS;QACT,oBAAoB,EAAE,WAAW;QACjC,kBAAkB,EAAE,GAAG;QACvB,QAAQ,EAAE,WAAW,CAAC,QAAQ;QAC9B,WAAW,EAAE,WAAW,CAAC,WAAW;QACpC,oBAAoB,EAAE,UAAU;QAChC,gBAAgB,EAAE,OAAO;QACzB,UAAU,EAAE,EAAE;QACd,KAAK;QACL,KAAK;KACN,CAAC;AACJ,CAAC;AAED,SAAS,IAAI,CACX,KAAuB,EACvB,OAAgB,EAChB,cAA6B,EAC7B,MAAc;IAEd,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,SAAS,GAAG,CAAC,CAAS;IACpB,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC;AACzC,CAAC;AAED,SAAS,OAAO,CAAC,KAAa,EAAE,GAAW;IACzC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,YAAY,CAAC,CAAC;IAC3C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,YAAY,CAAC,CAAC;IACzC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACzD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,EAAkB,EAClB,MAAc,EACd,WAAmB,EACnB,SAAiB;IAEjB,MAAM,GAAG,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IAChF,MAAM,OAAO,GAAG,EAAE;SACf,MAAM,EAAE;SACR,IAAI,CAAC,aAAa,CAAC;SACnB,KAAK,CAAC,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;SACvC,GAAG,EAAE,CAAC;IACT,MAAM,GAAG,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IAChF,MAAM,IAAI,GAAG,EAAE;SACZ,MAAM,EAAE;SACR,IAAI,CAAC,cAAc,CAAC;SACpB,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;SACxC,GAAG,EAAE,CAAC;IAET,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,IAAI,GAAG,CAAC,UAAU,KAAK,KAAK;YAAE,SAAS;QACvC,IAAI,GAAG,CAAC,IAAI,GAAG,WAAW,IAAI,GAAG,CAAC,IAAI,GAAG,SAAS;YAAE,SAAS;QAC7D,SAAS,IAAI,GAAG,CAAC,MAAM,CAAC;IAC1B,CAAC;IACD,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,GAAG,CAAC,UAAU,KAAK,KAAK;YAAE,SAAS;QACvC,IAAI,GAAG,CAAC,IAAI,GAAG,WAAW,IAAI,GAAG,CAAC,IAAI,GAAG,SAAS;YAAE,SAAS;QAC7D,WAAW,IAAI,GAAG,CAAC,MAAM,CAAC;IAC5B,CAAC;IACD,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,IAAI,GAAG,CAAC,IAAI,GAAG,WAAW,IAAI,GAAG,CAAC,IAAI,GAAG,SAAS;YAAE,SAAS;QAC7D,WAAW,IAAI,GAAG,CAAC,eAAe,CAAC;IACrC,CAAC;IAED,OAAO,cAAc,CAAC;QACpB,SAAS;QACT,oBAAoB,EAAE,WAAW;QACjC,kBAAkB,EAAE,WAAW;QAC/B,WAAW;QACX,SAAS;QACT,QAAQ,EAAE,IAAI,EAAE,QAAQ,IAAI,IAAI;KACjC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,EAAkB,EAClB,MAAc,EACd,MAAuB,EACvB,GAAG,GAAG,IAAI,IAAI,EAAE;IAEhB,MAAM,QAAQ,GAAG,EAAE;SAChB,MAAM,EAAE;SACR,IAAI,CAAC,uBAAuB,CAAC;SAC7B,KAAK,CACJ,GAAG,CACD,EAAE,CAAC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1C,EAAE,CAAC,uBAAuB,CAAC,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,EAC3D,EAAE,CAAC,uBAAuB,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,CACxD,CACF;SACA,GAAG,EAAE,CAAC;IACT,MAAM,MAAM,GAAG;QACb,IAAI,EAAE,MAAM,CAAC,SAAS;QACtB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC;QACxC,oBAAoB,EAAE,MAAM,CAAC,oBAAoB;QACjD,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,GAAG,CAAC,WAAW,EAAE;KAC7B,CAAC;IACF,IAAI,QAAQ,EAAE,CAAC;QACb,EAAE,CAAC,MAAM,CAAC,uBAAuB,CAAC;aAC/B,GAAG,CAAC,MAAM,CAAC;aACX,KAAK,CAAC,EAAE,CAAC,uBAAuB,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;aAClD,GAAG,EAAE,CAAC;QACT,OAAO;IACT,CAAC;IACD,EAAE,CAAC,MAAM,CAAC,uBAAuB,CAAC;SAC/B,MAAM,CAAC;QACN,EAAE,EAAE,UAAU,EAAE;QAChB,MAAM;QACN,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,GAAG,MAAM;KACV,CAAC;SACD,GAAG,EAAE,CAAC;AACX,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@agentsean/google",
+  "version": "1.0.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "drizzle-orm": "0.45.2",
+    "@agentsean/db": "1.0.0",
+    "@agentsean/credentials": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/seziro-team/agentsean.git",
+    "directory": "packages/google"
+  },
+  "homepage": "https://github.com/seziro-team/agentsean#readme",
+  "bugs": {
+    "url": "https://github.com/seziro-team/agentsean/issues"
+  },
+  "author": "Seziro (https://seziro.com)",
+  "description": "Agent Sean — google module",
+  "keywords": [
+    "seo",
+    "agent",
+    "agentsean",
+    "seo-automation"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/data','dist/data',{recursive:true})\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config ../../vitest.config.ts"
+  }
+}