@consilioweb/payload-seo-analyzer 1.12.0 → 1.13.0

package/dist/index.cjs

@@ -7392,6 +7392,137 @@ function createRankHistoryHandler() {
   };
 }
 
+// src/endpoints/ctrOpportunities.ts
+function expectedCtrForPosition(pos) {
+  const table = {
+    1: 0.28,
+    2: 0.15,
+    3: 0.1,
+    4: 0.07,
+    5: 0.055,
+    6: 0.045,
+    7: 0.035,
+    8: 0.03,
+    9: 0.025,
+    10: 0.022
+  };
+  if (pos <= 1) return table[1];
+  if (pos <= 10) {
+    const lo = Math.floor(pos);
+    const hi = Math.ceil(pos);
+    const a = table[lo] ?? 0.02;
+    const b = table[hi] ?? 0.02;
+    return a + (b - a) * (pos - lo);
+  }
+  if (pos <= 20) return 0.012;
+  return 5e-3;
+}
+function rankCtrOpportunities(rows, opts = {}) {
+  const minImpressions = opts.minImpressions ?? 50;
+  const maxPosition = opts.maxPosition ?? 20;
+  const out = [];
+  for (const r of rows) {
+    const url = r.keys?.[0];
+    if (!url) continue;
+    if (r.impressions < minImpressions) continue;
+    if (r.position > maxPosition) continue;
+    const expectedCtr = expectedCtrForPosition(r.position);
+    const gap = expectedCtr - r.ctr;
+    if (gap <= 0) continue;
+    const potentialClicks = Math.round(r.impressions * gap);
+    if (potentialClicks < 1) continue;
+    out.push({
+      url,
+      impressions: r.impressions,
+      clicks: r.clicks,
+      ctr: r.ctr,
+      position: Math.round(r.position * 10) / 10,
+      expectedCtr: Math.round(expectedCtr * 1e3) / 1e3,
+      potentialClicks
+    });
+  }
+  out.sort((a, b) => b.potentialClicks - a.potentialClicks);
+  return out;
+}
+async function resolveDoc(payload, url, targetCollections) {
+  let path;
+  try {
+    path = new URL(url).pathname;
+  } catch {
+    return null;
+  }
+  const segments = path.split("/").filter(Boolean);
+  const slug = segments.length === 0 ? "home" : segments[segments.length - 1];
+  for (const collection of targetCollections) {
+    try {
+      const res = await payload.find({
+        collection,
+        where: { slug: { equals: slug } },
+        limit: 1,
+        depth: 0,
+        overrideAccess: true
+      });
+      if (res.docs.length > 0) {
+        return { collection, id: String(res.docs[0].id) };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function createCtrOpportunitiesHandler(basePath, targetCollections, seoConfig) {
+  return async (req) => {
+    try {
+      if (!isGscAdmin(req.user)) return Response.json({ error: "Forbidden" }, { status: 403 });
+      const cfg = getGscOAuthConfig(basePath, seoConfig);
+      if (!cfg) return Response.json({ error: "GSC OAuth not configured." }, { status: 400 });
+      const authDoc = await getOrCreateGscAuthDoc(req.payload);
+      if (!authDoc.refreshTokenEnc) {
+        return Response.json({ error: "Not connected to Google Search Console." }, { status: 409 });
+      }
+      let accessToken;
+      try {
+        accessToken = await getGscAccessToken(req.payload, cfg, authDoc);
+      } catch (e) {
+        const code = e instanceof Error ? e.message : "refresh_failed";
+        const status = code === "decrypt_failed" ? 409 : 502;
+        return Response.json({ error: "Could not refresh GSC access token." }, { status });
+      }
+      const url = new URL(req.url);
+      const minImpressions = Math.max(1, parseInt(url.searchParams.get("minImpressions") || "50", 10) || 50);
+      const property = authDoc.propertyUrl || cfg.siteUrl;
+      const end = new Date(Date.now() - 2 * 864e5);
+      const start = new Date(end.getTime() - 27 * 864e5);
+      const endDate = end.toISOString().slice(0, 10);
+      const startDate = start.toISOString().slice(0, 10);
+      let rows;
+      try {
+        rows = await queryGscSearchAnalytics(accessToken, property, {
+          startDate,
+          endDate,
+          dimensions: ["page"],
+          rowLimit: 250
+        });
+      } catch (e) {
+        return Response.json({ error: e instanceof Error ? e.message : "GSC query failed" }, { status: 502 });
+      }
+      const opportunities = rankCtrOpportunities(rows, { minImpressions });
+      const top = opportunities.slice(0, 50);
+      const resolved = await Promise.all(
+        top.map(async (o) => ({ ...o, doc: await resolveDoc(req.payload, o.url, targetCollections) }))
+      );
+      return Response.json(
+        { property, startDate, endDate, count: opportunities.length, opportunities: resolved },
+        { headers: { "Cache-Control": "no-store" } }
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Internal server error";
+      req.payload.logger.error(`[seo] ctr-opportunities error: ${message}`);
+      return Response.json({ error: message }, { status: 500 });
+    }
+  };
+}
+
 // src/rateLimiter.ts
 function createRateLimiter(maxRequests, windowMs) {
   const store = /* @__PURE__ */ new Map();
@@ -10518,7 +10649,8 @@ var seoAnalyzerPlugin = (pluginConfig = {}) => (incomingConfig) => {
       { path: `${basePath}/gsc/data`, method: "get", handler: withRateLimit(createGscDataHandler(basePath, seoConfig)) },
       { path: `${basePath}/gsc/disconnect`, method: "post", handler: createGscDisconnectHandler() },
       { path: `${basePath}/rank-snapshot`, method: "post", handler: withRateLimit(createRankSnapshotHandler(basePath, seoConfig)) },
-      { path: `${basePath}/rank-history`, method: "get", handler: createRankHistoryHandler() }
+      { path: `${basePath}/rank-history`, method: "get", handler: createRankHistoryHandler() },
+      { path: `${basePath}/ctr-opportunities`, method: "get", handler: createCtrOpportunitiesHandler(basePath, targetCollections, seoConfig) }
     );
   }
   if (features.alerts) {

package/dist/index.js

@@ -7390,6 +7390,137 @@ function createRankHistoryHandler() {
   };
 }
 
+// src/endpoints/ctrOpportunities.ts
+function expectedCtrForPosition(pos) {
+  const table = {
+    1: 0.28,
+    2: 0.15,
+    3: 0.1,
+    4: 0.07,
+    5: 0.055,
+    6: 0.045,
+    7: 0.035,
+    8: 0.03,
+    9: 0.025,
+    10: 0.022
+  };
+  if (pos <= 1) return table[1];
+  if (pos <= 10) {
+    const lo = Math.floor(pos);
+    const hi = Math.ceil(pos);
+    const a = table[lo] ?? 0.02;
+    const b = table[hi] ?? 0.02;
+    return a + (b - a) * (pos - lo);
+  }
+  if (pos <= 20) return 0.012;
+  return 5e-3;
+}
+function rankCtrOpportunities(rows, opts = {}) {
+  const minImpressions = opts.minImpressions ?? 50;
+  const maxPosition = opts.maxPosition ?? 20;
+  const out = [];
+  for (const r of rows) {
+    const url = r.keys?.[0];
+    if (!url) continue;
+    if (r.impressions < minImpressions) continue;
+    if (r.position > maxPosition) continue;
+    const expectedCtr = expectedCtrForPosition(r.position);
+    const gap = expectedCtr - r.ctr;
+    if (gap <= 0) continue;
+    const potentialClicks = Math.round(r.impressions * gap);
+    if (potentialClicks < 1) continue;
+    out.push({
+      url,
+      impressions: r.impressions,
+      clicks: r.clicks,
+      ctr: r.ctr,
+      position: Math.round(r.position * 10) / 10,
+      expectedCtr: Math.round(expectedCtr * 1e3) / 1e3,
+      potentialClicks
+    });
+  }
+  out.sort((a, b) => b.potentialClicks - a.potentialClicks);
+  return out;
+}
+async function resolveDoc(payload, url, targetCollections) {
+  let path;
+  try {
+    path = new URL(url).pathname;
+  } catch {
+    return null;
+  }
+  const segments = path.split("/").filter(Boolean);
+  const slug = segments.length === 0 ? "home" : segments[segments.length - 1];
+  for (const collection of targetCollections) {
+    try {
+      const res = await payload.find({
+        collection,
+        where: { slug: { equals: slug } },
+        limit: 1,
+        depth: 0,
+        overrideAccess: true
+      });
+      if (res.docs.length > 0) {
+        return { collection, id: String(res.docs[0].id) };
+      }
+    } catch {
+    }
+  }
+  return null;
+}
+function createCtrOpportunitiesHandler(basePath, targetCollections, seoConfig) {
+  return async (req) => {
+    try {
+      if (!isGscAdmin(req.user)) return Response.json({ error: "Forbidden" }, { status: 403 });
+      const cfg = getGscOAuthConfig(basePath, seoConfig);
+      if (!cfg) return Response.json({ error: "GSC OAuth not configured." }, { status: 400 });
+      const authDoc = await getOrCreateGscAuthDoc(req.payload);
+      if (!authDoc.refreshTokenEnc) {
+        return Response.json({ error: "Not connected to Google Search Console." }, { status: 409 });
+      }
+      let accessToken;
+      try {
+        accessToken = await getGscAccessToken(req.payload, cfg, authDoc);
+      } catch (e) {
+        const code = e instanceof Error ? e.message : "refresh_failed";
+        const status = code === "decrypt_failed" ? 409 : 502;
+        return Response.json({ error: "Could not refresh GSC access token." }, { status });
+      }
+      const url = new URL(req.url);
+      const minImpressions = Math.max(1, parseInt(url.searchParams.get("minImpressions") || "50", 10) || 50);
+      const property = authDoc.propertyUrl || cfg.siteUrl;
+      const end = new Date(Date.now() - 2 * 864e5);
+      const start = new Date(end.getTime() - 27 * 864e5);
+      const endDate = end.toISOString().slice(0, 10);
+      const startDate = start.toISOString().slice(0, 10);
+      let rows;
+      try {
+        rows = await queryGscSearchAnalytics(accessToken, property, {
+          startDate,
+          endDate,
+          dimensions: ["page"],
+          rowLimit: 250
+        });
+      } catch (e) {
+        return Response.json({ error: e instanceof Error ? e.message : "GSC query failed" }, { status: 502 });
+      }
+      const opportunities = rankCtrOpportunities(rows, { minImpressions });
+      const top = opportunities.slice(0, 50);
+      const resolved = await Promise.all(
+        top.map(async (o) => ({ ...o, doc: await resolveDoc(req.payload, o.url, targetCollections) }))
+      );
+      return Response.json(
+        { property, startDate, endDate, count: opportunities.length, opportunities: resolved },
+        { headers: { "Cache-Control": "no-store" } }
+      );
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Internal server error";
+      req.payload.logger.error(`[seo] ctr-opportunities error: ${message}`);
+      return Response.json({ error: message }, { status: 500 });
+    }
+  };
+}
+
 // src/rateLimiter.ts
 function createRateLimiter(maxRequests, windowMs) {
   const store = /* @__PURE__ */ new Map();
@@ -10516,7 +10647,8 @@ var seoAnalyzerPlugin = (pluginConfig = {}) => (incomingConfig) => {
       { path: `${basePath}/gsc/data`, method: "get", handler: withRateLimit(createGscDataHandler(basePath, seoConfig)) },
       { path: `${basePath}/gsc/disconnect`, method: "post", handler: createGscDisconnectHandler() },
       { path: `${basePath}/rank-snapshot`, method: "post", handler: withRateLimit(createRankSnapshotHandler(basePath, seoConfig)) },
-      { path: `${basePath}/rank-history`, method: "get", handler: createRankHistoryHandler() }
+      { path: `${basePath}/rank-history`, method: "get", handler: createRankHistoryHandler() },
+      { path: `${basePath}/ctr-opportunities`, method: "get", handler: createCtrOpportunitiesHandler(basePath, targetCollections, seoConfig) }
     );
   }
   if (features.alerts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consilioweb/payload-seo-analyzer",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Payload CMS SEO plugin — 50+ checks, dashboard, Lexical JSON support, Flesch FR/EN readability, i18n",
   "type": "module",
   "main": "./dist/index.cjs",