feat: add projection support to suggestions API [SITES-39183] (#1693)

## Summary

Adds field projection via a `view` query parameter and optional status
filtering to the Suggestions API endpoints. This allows clients to
request lighter payloads optimized for specific UI needs (e.g.,
selection lists, table displays).

Implements API projection for suggestions with a schema-driven
architecture.
This PR integrates with spacecat-shared PR-1289 which provides
type-specific data schemas, validation, and projection logic.
adobe/spacecat-shared#1289

## Changes

### `view` parameter
Pre-defined projections for all GET suggestion endpoints:

| View | Returns | Use Case |
|------|---------|----------|
| `minimal` | `id`, `status`, URL-related `data` fields | Lightest
payload for selection lists |
| `summary` | Minimal + `opportunityId`, `type`, `rank`, `url`,
timestamps | Table displays without heavy data |
| `full` | All fields including `data` and `kpiDeltas` | Default,
backward compatible |

### `status` parameter
Filter suggestions by status (non-paginated endpoint only):

- Single status: `?status=NEW`
- Multiple statuses: `?status=NEW,APPROVED,IN_PROGRESS`
- Valid values: `NEW`, `APPROVED`, `SKIPPED`, `FIXED`, `ERROR`,
`IN_PROGRESS`, `OUTDATED`, `PENDING_VALIDATION`
- Returns `400 Bad Request` for invalid status values

> **Note:** Status filtering excluded from paginated endpoints to avoid
pagination inconsistencies. Use `/by-status/{status}/paged` for
paginated status-filtered results.

## Example Usage

### Minimal view for selection list
GET /sites/{siteId}/opportunities/{opptyId}/suggestions?view=minimal

### Summary view with status filter  
GET
/sites/{siteId}/opportunities/{opptyId}/suggestions?view=summary&status=NEW,FIXED

### Full view (default)
GET /sites/{siteId}/opportunities/{opptyId}/suggestions

---------

Co-authored-by: Kanishka <kanishka@adobe.com>

Author: Kanishkavijay39

README.md

@@ -61,6 +61,27 @@ $ npm install
 $ npm test
 ```
 
+### E2E Tests
+
+End-to-end tests validate the API against the live CI environment.
+
+#### Setup
+
+Add the following to your `.env` file:
+
+```plaintext
+USER_API_KEY=your_api_key_for_ci_environment
+```
+
+The E2E tests use a hardcoded test site ID and auto-discover opportunities/suggestions for testing.
+(You can change site id according to you)
+
+#### Run E2E Tests Locally
+
+```bash
+$ npm run test-e2e
+```
+
 ### Lint
 
 ```bash

docs/index.html

@@ -384,3 +384,43 @@ cursor:
   schema:
     type: string
     example: "eyJzayI6IjIwMjQtMDEtMTVUMTI6MzA6MDBaIiwiaWQiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAifQ=="
+
+suggestionView:
+  name: view
+  description: |
+    Projection view for suggestion response data. Controls which fields are returned.
+    - `minimal`: Returns id, status, timestamps (createdAt, updatedAt), and URL-related data fields (lightest payload for selection lists)
+    - `summary`: Returns key fields: id, opportunityId, type, rank, status, url, timestamps (excludes heavy data and kpiDeltas)
+    - `full`: Returns all fields including data and kpiDeltas (default, backward compatible)
+  in: query
+  required: false
+  schema:
+    type: string
+    enum:
+      - minimal
+      - summary
+      - full
+    default: full
+  example: summary
+
+suggestionStatus:
+  name: status
+  description: |
+    Filter suggestions by status. Supports single status or comma-separated multiple statuses.
+    When provided, only suggestions matching any of the specified statuses are returned.
+    
+    **Valid values:** NEW, APPROVED, SKIPPED, FIXED, ERROR, IN_PROGRESS, OUTDATED, PENDING_VALIDATION
+    
+    Returns 400 Bad Request if invalid status values are provided.
+  in: query
+  required: false
+  schema:
+    type: string
+    description: Single status or comma-separated statuses (e.g., "NEW" or "NEW,APPROVED")
+  examples:
+    single:
+      value: NEW
+      summary: Filter by single status
+    multiple:
+      value: NEW,APPROVED,IN_PROGRESS
+      summary: Filter by multiple statuses (comma-separated)

docs/openapi/parameters.yaml

@@ -2923,6 +2923,147 @@ SuggestionList:
   type: array
   items:
     $ref: '#/Suggestion'
+SuggestionMinimal:
+  type: object
+  description: Minimal suggestion projection containing id, status, timestamps, and URL-related data fields for listing views
+  properties:
+    id:
+      description: UUID of this suggestion
+      $ref: '#/Id'
+    status:
+      description: Status of this suggestion
+      $ref: '#/SuggestionStatus'
+    data:
+      type: object
+      description: URL-related fields extracted from the full data object. Only present if any URL fields exist.
+      properties:
+        url:
+          type: string
+          example: "https://example.com/page"
+        urls:
+          type: array
+          items:
+            type: string
+        urlFrom:
+          type: string
+          example: "https://example.com/source"
+        urlTo:
+          type: string
+          example: "https://example.com/destination"
+        url_from:
+          type: string
+          description: Source URL (snake_case variant for broken backlinks)
+          example: "https://example.com/source"
+        url_to:
+          type: string
+          description: Target URL (snake_case variant for broken backlinks)
+          example: "https://example.com/destination"
+        urlsSuggested:
+          type: array
+          description: Array of suggested URLs
+          items:
+            type: string
+        sitemapUrl:
+          type: string
+          example: "https://example.com/sitemap.xml"
+        pageUrl:
+          type: string
+          example: "https://example.com/page"
+        pattern:
+          type: string
+        link:
+          type: string
+        path:
+          type: string
+        sourceUrl:
+          type: string
+        destinationUrl:
+          type: string
+        recommendations:
+          type: array
+          items:
+            type: object
+        cves:
+          type: array
+          items:
+            type: object
+        findings:
+          type: array
+          items:
+            type: object
+        form:
+          type: object
+        page:
+          type: object
+        accessibility:
+          type: object
+        metrics:
+          type: object
+          description: CWV metrics (mobileMetric, desktopMetric) for calculating totalIssues
+        type:
+          type: string
+          description: Type indicator (e.g., 'url' vs 'group' for CWV)
+        pageviews:
+          type: number
+          description: Page views count for display
+        issues:
+          type: array
+          description: Issues array for Accessibility, ColorContrast, FormNonExperimental (includes occurrences field)
+          items:
+            type: object
+    createdAt:
+      description: UTC timestamp of when the suggestion was created
+      $ref: '#/DateTime'
+    updatedAt:
+      description: UTC timestamp of when the suggestion was last updated
+      $ref: '#/DateTime'
+  required:
+    - id
+    - status
+    - createdAt
+    - updatedAt
+SuggestionSummary:
+  type: object
+  description: Summary suggestion projection (superset of minimal, subset of full). Contains minimal data fields plus metadata for table displays.
+  properties:
+    id:
+      description: UUID of this suggestion
+      $ref: '#/Id'
+    status:
+      description: Status of this suggestion
+      $ref: '#/SuggestionStatus'
+    data:
+      type: object
+      description: URL-related fields from minimal view (same as SuggestionMinimal.data). Only present if any URL fields exist.
+    opportunityId:
+      description: UUID of the opportunity this suggestion belongs to
+      $ref: '#/Id'
+    type:
+      $ref: '#/SuggestionType'
+    rank:
+      description: Type-specific numeric rank value (e.g., "domainTraffic" for a broken-backlink) helps sorting
+      type: number
+      example: 45600
+    url:
+      description: URL associated with the suggestion (extracted from data). May be null if no URL found.
+      type: string
+      example: "https://example.com/page"
+    createdAt:
+      description: UTC timestamp of when the suggestion was created
+      $ref: '#/DateTime'
+    updatedAt:
+      description: UTC timestamp of when the suggestion was last updated
+      $ref: '#/DateTime'
+    updatedBy:
+      description: Who last updated this suggestion
+      type: string
+      example: "user@example.com"
+  required:
+    - id
+    - status
+    - opportunityId
+    - type
+    - rank
 PaginationMetadata:
   type: object
   description: Metadata for paginated responses

docs/openapi/schemas.yaml

@@ -195,10 +195,27 @@ site-opportunity-suggestions:
   parameters:
     - $ref: './parameters.yaml#/siteId'
     - $ref: './parameters.yaml#/opportunityId'
+    - $ref: './parameters.yaml#/suggestionView'
+    - $ref: './parameters.yaml#/suggestionStatus'
   get:
     operationId: getSiteOpportunitySuggestions
     summary: |
       Retrieve a list of all suggestions for a specific opportunity
+    description: |
+      Returns all suggestions (non-paginated) with optional field projection and status filtering.
+      
+      **Field Projection:**
+      - `view=minimal` - Returns id, status, timestamps (createdAt, updatedAt), and URL-related data fields (lightest)
+      - `view=summary` - Returns minimal fields plus metadata (opportunityId, type, rank, updatedBy)
+      - `view=full` - Returns all fields including complete data object (default)
+      
+      **Status Filtering:**
+      - Single status: `status=NEW`
+      - Multiple statuses: `status=NEW,APPROVED,IN_PROGRESS`
+      - Valid values: NEW, APPROVED, SKIPPED, FIXED, ERROR, IN_PROGRESS, OUTDATED, PENDING_VALIDATION
+      - Returns 400 Bad Request for invalid status values
+      
+      **Note:** For paginated results, use the `/paged` endpoints. Status filtering is only available on this non-paginated endpoint or the dedicated `/by-status` endpoints.
     tags:
       - opportunity-suggestions
     responses:
@@ -260,10 +277,13 @@ site-opportunity-suggestions-by-status:
       required: true
       schema:
         type: string
+    - $ref: './parameters.yaml#/suggestionView'
   get:
     operationId: getSiteOpportunitySuggestionsByStatus
     summary: |
       Retrieve suggestions for a specific opportunity filtered by status
+    description: |
+      Returns suggestions filtered by status with optional field projection using the view parameter.
     tags:
       - opportunity-suggestions
     responses:
@@ -293,12 +313,15 @@ site-opportunity-suggestions-paged:
     - $ref: './parameters.yaml#/siteId'
     - $ref: './parameters.yaml#/opportunityId'
     - $ref: './parameters.yaml#/limit'
+    - $ref: './parameters.yaml#/suggestionView'
   get:
     operationId: getSiteOpportunitySuggestionsPaged
     summary: |
       Retrieve a paginated list of suggestions for a specific opportunity
     description: |
       Returns suggestions in pages with pagination metadata. Use the cursor from the response to fetch subsequent pages.
+      Supports field projection using the view parameter to reduce response size.
+      Note: For status filtering, use the non-paginated endpoint or the by-status endpoints.
     tags:
       - opportunity-suggestions
     responses:
@@ -329,12 +352,15 @@ site-opportunity-suggestions-paged-with-cursor:
     - $ref: './parameters.yaml#/opportunityId'
     - $ref: './parameters.yaml#/limit'
     - $ref: './parameters.yaml#/cursor'
+    - $ref: './parameters.yaml#/suggestionView'
   get:
     operationId: getSiteOpportunitySuggestionsPagedWithCursor
     summary: |
       Retrieve a paginated list of suggestions for a specific opportunity using a cursor
     description: |
       Returns suggestions in pages with pagination metadata. Provide the cursor from a previous response to fetch the next page.
+      Supports field projection using the view parameter to reduce response size.
+      Note: For status filtering, use the non-paginated endpoint or the by-status endpoints.
     tags:
       - opportunity-suggestions
     responses:
@@ -369,12 +395,14 @@ site-opportunity-suggestions-by-status-paged:
       schema:
         type: string
     - $ref: './parameters.yaml#/limit'
+    - $ref: './parameters.yaml#/suggestionView'
   get:
     operationId: getSiteOpportunitySuggestionsByStatusPaged
     summary: |
       Retrieve a paginated list of suggestions for a specific opportunity filtered by status
     description: |
       Returns suggestions filtered by status in pages with pagination metadata. Use the cursor from the response to fetch subsequent pages.
+      Supports field projection using the view parameter to reduce response size.
     tags:
       - opportunity-suggestions
     responses:
@@ -410,12 +438,14 @@ site-opportunity-suggestions-by-status-paged-with-cursor:
         type: string
     - $ref: './parameters.yaml#/limit'
     - $ref: './parameters.yaml#/cursor'
+    - $ref: './parameters.yaml#/suggestionView'
   get:
     operationId: getSiteOpportunitySuggestionsByStatusPagedWithCursor
     summary: |
       Retrieve a paginated list of suggestions for a specific opportunity filtered by status using a cursor
     description: |
       Returns suggestions filtered by status in pages with pagination metadata. Provide the cursor from a previous response to fetch the next page.
+      Supports field projection using the view parameter to reduce response size.
     tags:
       - opportunity-suggestions
     responses:
@@ -520,10 +550,13 @@ site-opportunity-suggestion:
     - $ref: './parameters.yaml#/siteId'
     - $ref: './parameters.yaml#/opportunityId'
     - $ref: './parameters.yaml#/suggestionId'
+    - $ref: './parameters.yaml#/suggestionView'
   get:
     operationId: getSiteOpportunitySuggestion
     summary: |
       Retrieve details of a specific suggestion
+    description: |
+      Returns a single suggestion with optional field projection using the view parameter.
     tags:
       - opportunity-suggestions
     responses:

docs/openapi/site-opportunities.yaml

@@ -193,7 +193,10 @@ export class FixesController {
     if (res) return res;
 
     const suggestions = await fix.getSuggestions();
-    return ok(suggestions.map(SuggestionDto.toJSON));
+    return ok(suggestions.map((s) => {
+      const opportunity = s.getOpportunity();
+      return SuggestionDto.toJSON(s, 'full', opportunity);
+    }));
   }
 
   /**