feat: endpoint for PTAv2 summary

docs/openapi/api.yaml

@@ -248,6 +248,8 @@ paths:
     $ref: './site-paid.yaml#/site-traffic-paid-type-campaign'
   /sites/{siteId}/traffic/paid/type:
     $ref: './site-paid.yaml#/site-traffic-paid-type'
+  /sites/{siteId}/traffic/paid/pta2/weekly-summary:
+    $ref: './site-paid.yaml#/site-traffic-paid-pta2-weekly-summary'
   /sites/{siteId}/metrics/{metric}/{source}:
     $ref: './site-metrics-api.yaml#/site-metrics-by-source'
   /sites/{siteId}/metrics/{metric}/{source}/by-url/{base64PageUrl}:

docs/openapi/schemas.yaml

@@ -3461,6 +3461,47 @@ PaidSiteTopPageList:
   items:
     $ref: './schemas.yaml#/PaidSiteTopPage'
 
+PTAWeeklySummary:
+  type: object
+  description: Aggregated paid traffic analysis metrics for a specific week or month
+  properties:
+    pageviews:
+      type: string
+      description: Total number of pageviews
+      example: '885800'
+    click_rate:
+      type: string
+      description: Click-through rate as a decimal value
+      example: '0.40438022126890943'
+    engagement_rate:
+      type: string
+      description: Engagement rate as a decimal value
+      example: '0.4856626778053737'
+    bounce_rate:
+      type: string
+      description: Bounce rate as a decimal value
+      example: '0.5143373221946264'
+    trends:
+      type: object
+      description: Trend analysis showing percentage changes for each metric
+      properties:
+        pageviews:
+          type: number
+          description: Percentage change in pageviews
+          example: 7.084139264990329
+        click_rate:
+          type: number
+          description: Percentage change in click rate
+          example: -14.884651645383743
+        engagement_rate:
+          type: number
+          description: Percentage change in engagement rate
+          example: -9.782131803142791
+        bounce_rate:
+          type: number
+          description: Percentage change in bounce rate
+          example: 11.40608350861348
+
 LlmoQuestion:
   type: object
   required:

docs/openapi/site-paid.yaml

@@ -130,6 +130,37 @@ site-traffic-paid-type:
     security:
       - api_key: []
 
+site-traffic-paid-pta2-weekly-summary:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+    - $ref: './parameters.yaml#/weekNumber'
+    - $ref: './parameters.yaml#/month'
+    - $ref: './parameters.yaml#/year'
+  get:
+    tags:
+      - site
+      - paid
+    summary: Get PTA2 weekly summary for paid traffic
+    description: Returns aggregated paid traffic analysis metrics for a site for a specific week or month and year.
+    operationId: getPTA2WeeklySummary
+    responses:
+      '200':
+        description: PTA2 weekly summary data
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/PTAWeeklySummary'
+      '400':
+        $ref: './responses.yaml#/400'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: []
+
 site-traffic-paid-top-pages:
   parameters:
     - $ref: './parameters.yaml#/siteId'