@adobe/spacecat-shared-athena-client 1.1.1 → 1.2.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-athena-client-v1.2.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-athena-client-v1.2.0...@adobe/spacecat-shared-athena-client-v1.2.1) (2025-07-24)
+
+
+### Bug Fixes
+
+* mapping of traffic data response ([#871](https://github.com/adobe/spacecat-shared/issues/871)) ([ca65936](https://github.com/adobe/spacecat-shared/commit/ca659361b2f61c83bf995c285860d479e9f82066))
+
+# [@adobe/spacecat-shared-athena-client-v1.2.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-athena-client-v1.1.1...@adobe/spacecat-shared-athena-client-v1.2.0) (2025-07-24)
+
+
+### Features
+
+* ensure queries are shared so cache and api return same ([#866](https://github.com/adobe/spacecat-shared/issues/866)) ([b23d772](https://github.com/adobe/spacecat-shared/commit/b23d772a3a04355333ed090cc00386c33db6f872))
+
 # [@adobe/spacecat-shared-athena-client-v1.1.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-athena-client-v1.1.0...@adobe/spacecat-shared-athena-client-v1.1.1) (2025-07-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-athena-client",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Shared modules of the Spacecat Services - AWS Athena Client",
   "type": "module",
   "engines": {
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-athena": "3.848.0",
-    "@adobe/spacecat-shared-utils": "1.41.3"
+    "@adobe/spacecat-shared-utils": "1.43.0"
   },
   "devDependencies": {
     "chai": "5.2.1",

package/src/index.js

@@ -256,4 +256,11 @@ export class AWSAthenaClient {
   }
 }
 
-export { getTrafficAnalysisQuery, getTrafficAnalysisQueryPlaceholders } from './queries.js';
+export {
+  getTrafficAnalysisQuery,
+  getTrafficAnalysisQueryPlaceholders,
+  buildPageTypeCase,
+  getTrafficAnalysisQueryPlaceholdersFilled,
+} from './traffic-analysis/queries.js';
+export { TrafficDataResponseDto } from './traffic-analysis/traffic-data-base-response.js';
+export { TrafficDataWithCWVDto } from './traffic-analysis/traffic-data-with-cwv.js';

package/src/traffic-analysis/queries.js

@@ -0,0 +1,115 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { getStaticContent, getDateRanges } from '@adobe/spacecat-shared-utils';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const currentFile = fileURLToPath(import.meta.url);
+const currentDir = path.dirname(currentFile);
+
+const TRAFFIC_ANALYSIS_PATH = path.resolve(currentDir, '../../static/queries/traffic-analysis.sql.tpl');
+
+/**
+ * Loads the traffic analysis query template and applies placeholders.
+ * @param {Object} placeholders - Key-value pairs to replace in the query template.
+ * @param {Object} log - Logger (optional)
+ * @returns {Promise<string|null>} The templated SQL string or null on error.
+ */
+export async function getTrafficAnalysisQuery(placeholders = {}) {
+  return getStaticContent(placeholders, TRAFFIC_ANALYSIS_PATH);
+}
+
+/**
+ * Scans the query template and returns a sorted array of unique placeholder (strings).
+ * @returns {Promise<string[]>} Array of unique placeholder keys found in the template.
+ */
+export async function getTrafficAnalysisQueryPlaceholders() {
+  const raw = await getStaticContent({}, TRAFFIC_ANALYSIS_PATH);
+  const matches = raw.match(/{{\s*([\w]+)\s*}}/g);
+  return [...new Set((matches).map((m) => m.replace(/{{\s*|\s*}}/g, '')))].sort();
+}
+
+/**
+ * Returns case statement for pattern matching field to pageTypes
+ * @param {list} pageTypes - List containing name and pattern to use
+ * @param {string} column - Column to use for mapping.
+ * @returns {string|null} - Athena SQL case statement to project new column based on patterns.
+ */
+export function buildPageTypeCase(pageTypes, column) {
+  if (!pageTypes || !pageTypes.length) {
+    return null;
+  }
+
+  const caseLines = [
+    'CASE',
+    ...pageTypes.map(({ name, pattern }) => `    WHEN REGEXP_LIKE(${column}, '${pattern}') THEN '${name.replace(/'/g, "''")}'`),
+    "    ELSE 'other | Other Pages'",
+    'END AS page_type',
+  ];
+
+  return caseLines.join('\n');
+}
+
+/**
+ * Builds the placeholder values for the traffic analysis SQL template.
+ *
+ * @param {Object} params - Input parameters.
+ * @param {number} params.week - The ISO week number (1–53).
+ * @param {number} params.year - The year (e.g. 2025).
+ * @param {string} params.siteId - UUID of the site.
+ * @param {string[]} [params.dimensions- Dimensions to group by (e.g. ['utm_campaign', 'device']).
+ * @param {string} params.tableName - The name of the source table.
+ *  @param {string} params.pageTypeMatchColumn - The pageTypeMatchColumn of the source table.
+ * @param {Object|null} [params.pageTypes=null] - Optional pageType rules for CASE generation.
+ *
+ * @returns {Object} Template values for SQL generation.
+ */
+export function getTrafficAnalysisQueryPlaceholdersFilled({
+  week,
+  year,
+  siteId,
+  dimensions,
+  tableName,
+  pageTypes = null,
+  pageTypeMatchColumn = 'path',
+}) {
+  if (!week || !year || !siteId || !tableName) {
+    throw new Error('Missing required parameters: week, year, siteId, or tableName');
+  }
+
+  if (!Array.isArray(dimensions) || dimensions.length === 0) {
+    throw new Error('Missing dimension to group by');
+  }
+
+  const dimensionColumns = dimensions.join(', ');
+  const dimensionColumnsPrefixed = dimensions.map((col) => `a.${col}`).join(', ');
+
+  const dateRanges = getDateRanges(week, year);
+  const temporalCondition = dateRanges
+    .map((r) => `(year=${r.year} AND month=${r.month} AND week=${week})`)
+    .join(' OR ');
+
+  let pageTypeCase = 'NULL as page_type';
+  if (dimensions.includes('page_type') && pageTypes) {
+    pageTypeCase = buildPageTypeCase(pageTypes, pageTypeMatchColumn);
+  }
+
+  return {
+    siteId,
+    groupBy: dimensionColumns,
+    dimensionColumns,
+    dimensionColumnsPrefixed,
+    tableName,
+    temporalCondition,
+    pageTypeCase,
+  };
+}

package/src/traffic-analysis/traffic-data-base-response.js

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Data transfer object for Marketing Channel Response.
+ */
+export const TrafficDataResponseDto = {
+  /**
+   * Converts a traffic data object into a JSON object.
+   * @param {object} data - traffic data object.
+   * @returns {{
+   *   type: string,
+   *   channel: string,
+   *   platform: string,
+   *   campaign: string,
+   *   referrer: string,
+   *   pageviews: number,
+   *   pct_pageviews: number,
+   *   click_rate: number,
+   *   engagement_rate: number,
+   *   bounce_rate: number,
+   *   engaged_scroll: number,
+   *   p70_scroll: number,
+   * }} JSON object.
+   */
+  toJSON: (data) => ({
+    type: data.trf_type,
+    channel: data.trf_channel,
+    platform: data.trf_platform,
+    utm_source: data.utm_source,
+    utm_medium: data.utm_medium,
+    campaign: data.utm_campaign,
+    referrer: data.referrer,
+    pageviews: data.pageviews,
+    pct_pageviews: data.pct_pageviews,
+    click_rate: data.click_rate,
+    engagement_rate: data.engagement_rate,
+    bounce_rate: data.bounce_rate,
+    engaged_scroll: data.engaged_scroll,
+    p70_scroll: data.p70_scroll,
+  }),
+};

package/src/traffic-analysis/traffic-data-with-cwv.js

@@ -0,0 +1,97 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/* eslint-disable camelcase */
+import { TrafficDataResponseDto } from './traffic-data-base-response.js';
+
+const DEFAULT_THRESHOLDS = {
+  LCP_GOOD: 2500,
+  LCP_NEEDS_IMPROVEMENT: 4000,
+  INP_GOOD: 200,
+  INP_NEEDS_IMPROVEMENT: 500,
+  CLS_GOOD: 0.1,
+  CLS_NEEDS_IMPROVEMENT: 0.25,
+};
+
+function getThreshold(key, config) {
+  return key in config ? config[key] : DEFAULT_THRESHOLDS[key];
+}
+
+function scoreCWV(metric, val, config) {
+  const GOOD = getThreshold(`${metric}_GOOD`, config);
+  const NEEDS_IMPROVEMENT = getThreshold(`${metric}_NEEDS_IMPROVEMENT`, config);
+
+  if (val <= GOOD) return 'good';
+  if (val <= NEEDS_IMPROVEMENT) return 'needs improvement';
+  return 'poor';
+}
+
+/**
+ * Converts marketing traffic data into enriched DTO with CWV scores.
+ */
+export const TrafficDataWithCWVDto = {
+  /**
+   * @param {object} data - Raw data input.
+   * @param {object} [thresholdConfig] - Optional override for CWV thresholds.
+   * @returns {{
+   *   type: string,
+   *   channel: string,
+   *   campaign: string,
+   *   pageviews: number,
+   *   pct_pageviews: number,
+   *   click_rate: number,
+   *   engagement_rate: number,
+   *   bounce_rate: number,
+   *   p70_lcp: number,
+   *   p70_cls: number,
+   *   p70_inp: number,
+   *   lcp_score: string,
+   *   inp_score: string,
+   *   cls_score: string,
+   *   overall_cwv_score: string,
+   * }} JSON object.
+     */
+  toJSON: (data, thresholdConfig, baseUrl) => {
+    const lcp = Number(data.p70_lcp);
+    const inp = Number(data.p70_inp);
+    const cls = Number(data.p70_cls);
+
+    const lcp_score = scoreCWV('LCP', lcp, thresholdConfig);
+    const inp_score = scoreCWV('INP', inp, thresholdConfig);
+    const cls_score = scoreCWV('CLS', cls, thresholdConfig);
+
+    const scores = [lcp_score, inp_score, cls_score];
+    let overall_cwv_score;
+    if (scores.includes('poor')) {
+      overall_cwv_score = 'poor';
+    } else if (scores.includes('needs improvement')) {
+      overall_cwv_score = 'needs improvement';
+    } else {
+      overall_cwv_score = 'good';
+    }
+
+    return {
+      ...TrafficDataResponseDto.toJSON(data),
+      url: data.url || (baseUrl && data.path ? `${baseUrl.replace(/\/$/, '')}/${data.path.replace(/^\//, '')}` : undefined),
+      path: data.path,
+      page_type: data.page_type,
+      device: data.device,
+      p70_lcp: lcp,
+      p70_cls: cls,
+      p70_inp: inp,
+      lcp_score,
+      inp_score,
+      cls_score,
+      overall_cwv_score,
+    };
+  },
+};

package/static/queries/traffic-analysis.sql.tpl

@@ -1,55 +1,59 @@
 WITH raw AS (
     SELECT
-        trf_type,
         path,
-        {{pageTypeCase}},
+        {{pageTypeCase}},   
+        trf_type,
         trf_channel,
-        utm_campaign,
         trf_platform,
         device,
+        utm_source,
+        utm_medium,
+        utm_campaign,
+        referrer,
+        consent,
+        notfound,
         pageviews,
         clicked,
         engaged,
+        latest_scroll,
+        CASE WHEN latest_scroll >= 10000 THEN 1 ELSE 0 END AS engaged_scroll,  
         lcp,
         cls,
         inp
     FROM {{tableName}}
     WHERE siteid = '{{siteId}}'
-        AND ({{temporalCondition}})
+    AND ({{temporalCondition}})
 ),
-  
 agg AS (
     SELECT
         {{dimensionColumns}},
         COUNT(*)                          AS row_count,
-        CAST(SUM(pageviews) AS BIGINT)    AS pageviews,
-        CAST(SUM(clicked) AS BIGINT)      AS clicks,
-        CAST(SUM(engaged) AS BIGINT)      AS engagements,
-        approx_percentile(lcp, 0.70)      AS p70_lcp,
-        approx_percentile(cls, 0.70)      AS p70_cls,
-        approx_percentile(inp, 0.70)      AS p70_inp
+        CAST(SUM(pageviews) AS BIGINT)   AS pageviews,
+        CAST(SUM(clicked) AS BIGINT)     AS clicks,
+        CAST(SUM(engaged) AS BIGINT)     AS engagements,
+        CAST(SUM(engaged_scroll) AS BIGINT) AS engaged_scroll,
+        approx_percentile(latest_scroll, 0.70) AS p70_scroll,
+        approx_percentile(lcp, 0.70)     AS p70_lcp,
+        approx_percentile(cls, 0.70)     AS p70_cls,
+        approx_percentile(inp, 0.70)     AS p70_inp
     FROM raw
-    GROUP BY
-        {{groupBy}}
+    GROUP BY {{groupBy}}
 ),
-  
 grand_total AS (
     SELECT CAST(SUM(pageviews) AS BIGINT) AS total_pv FROM agg
 )
-  
 SELECT
     {{dimensionColumnsPrefixed}},
     a.pageviews,
-  
-    CAST(a.pageviews AS double) / NULLIF(t.total_pv, 0)            AS pct_pageviews,
-    CAST(a.clicks AS double)      / NULLIF(a.row_count, 0)         AS click_rate,
-    CAST(a.engagements AS double) / NULLIF(a.row_count, 0)         AS engagement_rate,
-    1 - CAST(a.engagements AS double) / NULLIF(a.row_count, 0)     AS bounce_rate,
-  
+    CAST(a.pageviews AS DOUBLE) / NULLIF(t.total_pv, 0)         AS pct_pageviews,
+    CAST(a.clicks AS DOUBLE)      / NULLIF(a.row_count, 0)      AS click_rate,
+    CAST(a.engagements AS DOUBLE) / NULLIF(a.row_count, 0)      AS engagement_rate,
+    1 - CAST(a.engagements AS DOUBLE) / NULLIF(a.row_count, 0)  AS bounce_rate,
+    a.engaged_scroll,
+    a.p70_scroll,
     a.p70_lcp,
     a.p70_cls,
     a.p70_inp
-  
 FROM agg a
 CROSS JOIN grand_total t
 ORDER BY a.pageviews DESC

package/src/queries.js

@@ -1,34 +0,0 @@
-/*
- * Copyright 2025 Adobe. All rights reserved.
- * This file is licensed to you under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License. You may obtain a copy
- * of the License at http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under
- * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
- * OF ANY KIND, either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
-import { getStaticContent } from '@adobe/spacecat-shared-utils';
-
-const TRAFIC_ANALYSIS_PATH = 'static/queries/traffic-analysis.sql.tpl';
-
-/**
- * Loads the traffic analysis query template and applies placeholders.
- * @param {Object} placeholders - Key-value pairs to replace in the query template.
- * @param {Object} log - Logger (optional)
- * @returns {Promise<string|null>} The templated SQL string or null on error.
- */
-export async function getTrafficAnalysisQuery(placeholders = {}) {
-  return getStaticContent(placeholders, TRAFIC_ANALYSIS_PATH);
-}
-
-/**
- * Scans the query template and returns a sorted array of unique placeholder (strings).
- * @returns {Promise<string[]>} Array of unique placeholder keys found in the template.
- */
-export async function getTrafficAnalysisQueryPlaceholders() {
-  const raw = await getStaticContent({}, TRAFIC_ANALYSIS_PATH);
-  const matches = raw.match(/{{\s*([\w]+)\s*}}/g);
-  return [...new Set((matches).map((m) => m.replace(/{{\s*|\s*}}/g, '')))].sort();
-}