@adobe/spacecat-shared-athena-client 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [@adobe/spacecat-shared-athena-client-v1.5.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-athena-client-v1.4.1...@adobe/spacecat-shared-athena-client-v1.5.0) (2025-11-10)
+
+
+### Features
+
+* added trend info to PTAv2 query ([#1109](https://github.com/adobe/spacecat-shared/issues/1109)) ([051a12a](https://github.com/adobe/spacecat-shared/commit/051a12a20fd10641b1e80dd31a3102a72c931bf9))
+
 # [@adobe/spacecat-shared-athena-client-v1.4.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-athena-client-v1.4.0...@adobe/spacecat-shared-athena-client-v1.4.1) (2025-11-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-athena-client",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Shared modules of the Spacecat Services - AWS Athena Client",
   "type": "module",
   "engines": {

package/src/index.d.ts

@@ -82,3 +82,50 @@ export declare class AWSAthenaClient {
 }
 
 export type Context = Parameters<typeof AWSAthenaClient.fromContext>[0];
+
+// PTA2 Query Types
+export interface PTAQueryParams {
+  siteId: string;
+  tableName: string;
+  week?: number;
+  month?: number;
+  year: number;
+}
+
+export interface PTASummaryData {
+  pageviews: number;
+  click_rate: number;
+  engagement_rate: number;
+  bounce_rate: number;
+}
+
+export interface PTATrendData {
+  pageviews: number;
+  click_rate: number;
+  engagement_rate: number;
+  bounce_rate: number;
+  trends: {
+    pageviews: number | null;
+    click_rate: number | null;
+    engagement_rate: number | null;
+    bounce_rate: number | null;
+  } | null;
+}
+
+export declare function getPreviousPeriod(params: {
+  week?: number;
+  month?: number;
+  year: number;
+}): { week?: number; month?: number; year: number };
+
+export declare function getPTASummaryQuery(params: PTAQueryParams): string;
+
+export declare function getPTASummaryWithTrendQuery(params: PTAQueryParams): string;
+
+export declare const PTASummaryResponseDto: {
+  toJSON: (data: Record<string, unknown>) => PTASummaryData;
+};
+
+export declare const PTASummaryWithTrendResponseDto: {
+  toJSON: (data: Array<Record<string, unknown>>) => PTATrendData;
+};

package/src/index.js

@@ -265,4 +265,10 @@ export {
 export { TrafficDataResponseDto } from './traffic-analysis/traffic-data-base-response.js';
 export { TrafficDataWithCWVDto } from './traffic-analysis/traffic-data-with-cwv.js';
 
-export { getPTASummaryQuery, PTASummaryResponseDto } from './pta2/queries.js';
+export {
+  getPreviousPeriod,
+  getPTASummaryQuery,
+  getPTASummaryWithTrendQuery,
+  PTASummaryResponseDto,
+  PTASummaryWithTrendResponseDto,
+} from './pta2/queries.js';

package/src/pta2/queries.js

@@ -12,6 +12,40 @@
 
 import { getTemporalCondition } from '@adobe/spacecat-shared-utils';
 
+/**
+ * Calculates the previous period (week or month) for trend comparison.
+ * @param {Object} params - Period parameters
+ * @param {number} params.week - Week number (optional)
+ * @param {number} params.month - Month number (optional)
+ * @param {number} params.year - Year number
+ * @returns {Object} Previous period with week/month and year
+ */
+export function getPreviousPeriod({ week, month, year }) {
+  if (week !== undefined) {
+    // Calculate previous week
+    const prevWeek = week - 1;
+    if (prevWeek < 1) {
+      // Move to previous year's last week
+      const prevYear = year - 1;
+      // Approximate last week (52 or 53)
+      return { week: 52, year: prevYear };
+    }
+    return { week: prevWeek, year };
+  }
+
+  if (month !== undefined) {
+    // Calculate previous month
+    const prevMonth = month - 1;
+    if (prevMonth < 1) {
+      // Move to previous year's December
+      return { month: 12, year: year - 1 };
+    }
+    return { month: prevMonth, year };
+  }
+
+  throw new Error('Either week or month must be provided');
+}
+
 /**
  * Generates the PTA summary query template using template literals.
  * @param {Object} params - Template parameters
@@ -56,6 +90,61 @@ export function getPTASummaryQuery({
   `;
 }
 
+/**
+ * Generates a PTA summary query that includes both current and previous period data
+ * for trend analysis. More efficient than making two separate queries.
+ * @param {Object} params - Template parameters
+ * @param {string} params.siteId - Site ID
+ * @param {string} params.tableName - Table name
+ * @param {number} params.week - Week number (either week or month must be provided)
+ * @param {number} params.month - Month number (either week or month must be provided)
+ * @param {number} params.year - Year number
+ * @returns {string} The SQL query string with both current and previous period data
+ */
+export function getPTASummaryWithTrendQuery({
+  siteId,
+  tableName,
+  week,
+  month,
+  year,
+}) {
+  if (!siteId || !tableName) {
+    throw new Error('Missing required parameters: siteId, or tableName');
+  }
+
+  if ((!week && !month) || !year) {
+    throw new Error('Missing required parameters: week, month or year');
+  }
+
+  const currentTemporalCondition = getTemporalCondition({ week, month, year });
+  const previousPeriod = getPreviousPeriod({ week, month, year });
+  const previousTemporalCondition = getTemporalCondition(previousPeriod);
+
+  return `
+  SELECT
+        period,
+        CAST(SUM(pageviews) AS BIGINT) AS total_pageviews,
+        CAST(SUM(clicked) AS BIGINT) AS total_clicks,
+        CAST(SUM(engaged) AS BIGINT) AS total_engaged,
+        COUNT(*) AS total_rows,
+        CAST(SUM(clicked) AS DOUBLE) / NULLIF(COUNT(*), 0) AS click_rate,
+        CAST(SUM(engaged) AS DOUBLE) / NULLIF(COUNT(*), 0) AS engagement_rate,
+        1 - CAST(SUM(engaged) AS DOUBLE) / NULLIF(COUNT(*), 0) AS bounce_rate
+    FROM (
+        SELECT *, 'current' as period FROM ${tableName}
+        WHERE siteid = '${siteId}'
+            AND (${currentTemporalCondition})
+            AND trf_type = 'paid'
+        UNION ALL
+        SELECT *, 'previous' as period FROM ${tableName}
+        WHERE siteid = '${siteId}'
+            AND (${previousTemporalCondition})
+            AND trf_type = 'paid'
+    )
+    GROUP BY period
+  `;
+}
+
 export const PTASummaryResponseDto = {
   /**
    * Converts a traffic data object into a JSON object.
@@ -74,3 +163,64 @@ export const PTASummaryResponseDto = {
     bounce_rate: data.bounce_rate,
   }),
 };
+
+export const PTASummaryWithTrendResponseDto = {
+  /**
+   * Converts trend data (array with current and previous periods)
+   * into a JSON object with current metrics and trends.
+   * @param {Array<object>} data - Array of traffic data objects with 'period' field.
+   * @returns {{
+   *   pageviews: number,
+   *   click_rate: number,
+   *   engagement_rate: number,
+   *   bounce_rate: number,
+   *   trends: {
+   *     pageviews: number,
+   *     click_rate: number,
+   *     engagement_rate: number,
+   *     bounce_rate: number
+   *   }
+   * }} JSON object with current metrics and trend percentages.
+   */
+  toJSON: (data) => {
+    if (!Array.isArray(data) || data.length === 0) {
+      throw new Error('Expected an array with at least one period');
+    }
+
+    const currentData = data.find((row) => row.period === 'current');
+    const previousData = data.find((row) => row.period === 'previous');
+
+    if (!currentData) {
+      throw new Error('Current period data not found');
+    }
+
+    const current = {
+      pageviews: currentData.total_pageviews,
+      click_rate: currentData.click_rate,
+      engagement_rate: currentData.engagement_rate,
+      bounce_rate: currentData.bounce_rate,
+    };
+
+    // Calculate trend percentages (null if no previous data)
+    const trends = previousData ? {
+      pageviews: previousData.total_pageviews > 0
+        ? ((current.pageviews - previousData.total_pageviews) / previousData.total_pageviews) * 100
+        : null,
+      click_rate: previousData.click_rate > 0
+        ? ((current.click_rate - previousData.click_rate) / previousData.click_rate) * 100
+        : null,
+      engagement_rate: previousData.engagement_rate > 0
+        ? ((current.engagement_rate - previousData.engagement_rate)
+          / previousData.engagement_rate) * 100
+        : null,
+      bounce_rate: previousData.bounce_rate > 0
+        ? ((current.bounce_rate - previousData.bounce_rate) / previousData.bounce_rate) * 100
+        : null,
+    } : null;
+
+    return {
+      ...current,
+      trends,
+    };
+  },
+};