From 5ee539e517bd983605c40b4dc6c8d44ddee1b01a Mon Sep 17 00:00:00 2001
From: Alexandru Tudoran <atudoran@adobe.com>
Date: Mon, 27 Oct 2025 17:18:43 +0200
Subject: [PATCH 1/3] tud onboarding

---
 docs/openapi/api.yaml           |  10 +
 docs/openapi/schemas.yaml       | 217 ++++++++++++
 docs/openapi/url-store-api.yaml | 328 +++++++++++++++++++
 src/controllers/url-store.js    | 564 ++++++++++++++++++++++++++++++++
 src/index.js                    |   3 +
 src/routes/index.js             |  12 +
 6 files changed, 1134 insertions(+)
 create mode 100644 docs/openapi/url-store-api.yaml
 create mode 100644 src/controllers/url-store.js

diff --git a/docs/openapi/api.yaml b/docs/openapi/api.yaml
index 357b725c4..08ec592a6 100644
--- a/docs/openapi/api.yaml
+++ b/docs/openapi/api.yaml
@@ -67,6 +67,8 @@ tags:
     description: Report generation and management operations
   - name: project
     description: Project management operations
+  - name: site urls
+    description: Site URL tracking and management operations
 
 paths:
   /audits/latest/{auditType}:
@@ -214,6 +216,14 @@ paths:
     $ref: './site-top-pages-api.yaml#/site-top-pages-by-source'
   /sites/{siteId}/top-pages/{source}/{geo}:
     $ref: './site-top-pages-api.yaml#/site-top-pages-by-source-and-geo'
+  /sites/{siteId}/url-store:
+    $ref: './url-store-api.yaml#/url-store-list'
+  /sites/{siteId}/url-store/by-source/{source}:
+    $ref: './url-store-api.yaml#/url-store-by-source'
+  /sites/{siteId}/url-store/by-audit/{auditType}:
+    $ref: './url-store-api.yaml#/url-store-by-audit'
+  /sites/{siteId}/url-store/{base64Url}:
+    $ref: './url-store-api.yaml#/url-store-get'
   /sites/{siteId}/traffic/paid:
     $ref: './site-paid.yaml#/site-traffic-paid-top-pages'
   /sites/{siteId}/traffic/paid/url-page-type:
diff --git a/docs/openapi/schemas.yaml b/docs/openapi/schemas.yaml
index c8c13d396..9d092d8aa 100644
--- a/docs/openapi/schemas.yaml
+++ b/docs/openapi/schemas.yaml
@@ -1636,6 +1636,223 @@ SiteTopPageList:
   type: array
   items:
     $ref: './schemas.yaml#/SiteTopPage'
+AuditUrl:
+  type: object
+  required:
+    - siteId
+    - url
+    - source
+    - audits
+    - createdAt
+    - updatedAt
+    - createdBy
+    - updatedBy
+  properties:
+    siteId:
+      description: Parent site identifier
+      $ref: '#/Id'
+    url:
+      description: URL after canonicalization
+      $ref: '#/URL'
+    source:
+      description: Origin of the URL
+      type: string
+      default: manual
+      example: manual
+    audits:
+      description: Enabled audit types
+      type: array
+      items:
+        type: string
+      example: ['accessibility', 'broken-backlinks']
+    createdAt:
+      description: ISO 8601 timestamp when created
+      $ref: '#/DateTime'
+    updatedAt:
+      description: ISO 8601 timestamp when last modified
+      $ref: '#/DateTime'
+    createdBy:
+      description: User/service who created this URL
+      type: string
+      example: user-alice
+    updatedBy:
+      description: Last user/service to modify this URL
+      type: string
+      example: user-bob
+  example:
+    siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
+    url: 'https://example.com/documents/report.pdf'
+    source: 'manual'
+    audits: ['accessibility', 'broken-backlinks']
+    createdAt: '2025-10-10T12:00:00Z'
+    updatedAt: '2025-10-10T15:30:00Z'
+    createdBy: 'user-alice'
+    updatedBy: 'user-bob'
+AuditUrlInput:
+  type: object
+  required:
+    - url
+    - audits
+  properties:
+    url:
+      description: The URL to add
+      $ref: '#/URL'
+    source:
+      description: Origin of the URL (defaults to "manual")
+      type: string
+      default: manual
+    audits:
+      description: Enabled audit types
+      type: array
+      items:
+        type: string
+      example: ['accessibility', 'broken-backlinks']
+  example:
+    url: 'https://example.com/page1.html'
+    source: 'manual'
+    audits: ['accessibility', 'broken-backlinks']
+AuditUrlUpdate:
+  type: object
+  required:
+    - url
+    - audits
+  properties:
+    url:
+      description: The URL to update
+      $ref: '#/URL'
+    audits:
+      description: Enabled audit types (overrides existing)
+      type: array
+      items:
+        type: string
+      example: ['accessibility']
+  example:
+    url: 'https://example.com/page1.html'
+    audits: ['accessibility']
+AuditUrlListResponse:
+  type: object
+  required:
+    - items
+  properties:
+    items:
+      type: array
+      items:
+        $ref: './schemas.yaml#/AuditUrl'
+    cursor:
+      description: Pagination cursor for next page
+      type: string
+  example:
+    items:
+      - siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
+        url: 'https://example.com/page1.html'
+        source: 'manual'
+        audits: ['accessibility']
+        createdAt: '2025-10-10T12:00:00Z'
+        updatedAt: '2025-10-10T15:30:00Z'
+        createdBy: 'user-alice'
+        updatedBy: 'user-bob'
+    cursor: 'eyJsYXN0S2V5Ijp7InNpdGVJZCI6ImV4YW1wbGUtY29tIn19'
+AuditUrlBulkResponse:
+  type: object
+  required:
+    - metadata
+    - failures
+    - items
+  properties:
+    metadata:
+      type: object
+      required:
+        - total
+        - success
+        - failure
+      properties:
+        total:
+          type: integer
+          description: Total number of URLs in the request
+        success:
+          type: integer
+          description: Number of successfully processed URLs
+        failure:
+          type: integer
+          description: Number of failed URLs
+    failures:
+      type: array
+      items:
+        type: object
+        required:
+          - url
+          - reason
+        properties:
+          url:
+            type: string
+          reason:
+            type: string
+      description: Per-item error information
+    items:
+      type: array
+      items:
+        $ref: './schemas.yaml#/AuditUrl'
+      description: Successfully processed URLs
+  example:
+    metadata:
+      total: 3
+      success: 2
+      failure: 1
+    failures:
+      - url: 'https://example.com/invalid'
+        reason: 'Invalid URL format'
+    items:
+      - siteId: 'a1b2c3d4-e5f6-7g8h-9i0j-k11l12m13n14'
+        url: 'https://example.com/page1.html'
+        source: 'manual'
+        audits: ['accessibility']
+        createdAt: '2025-10-10T12:00:00Z'
+        updatedAt: '2025-10-10T15:30:00Z'
+        createdBy: 'user-alice'
+        updatedBy: 'user-bob'
+AuditUrlDeleteResponse:
+  type: object
+  required:
+    - metadata
+    - failures
+  properties:
+    metadata:
+      type: object
+      required:
+        - total
+        - success
+        - failure
+      properties:
+        total:
+          type: integer
+          description: Total number of URLs in the request
+        success:
+          type: integer
+          description: Number of successfully deleted URLs
+        failure:
+          type: integer
+          description: Number of failed deletions
+    failures:
+      type: array
+      items:
+        type: object
+        required:
+          - url
+          - reason
+        properties:
+          url:
+            type: string
+          reason:
+            type: string
+      description: Per-item error information
+  example:
+    metadata:
+      total: 3
+      success: 2
+      failure: 1
+    failures:
+      - url: 'https://example.com/from-sitemap'
+        reason: 'Can only delete URLs with source: manual'
 SiteExperimentVariant:
   type: object
   properties:
diff --git a/docs/openapi/url-store-api.yaml b/docs/openapi/url-store-api.yaml
new file mode 100644
index 000000000..62a360c02
--- /dev/null
+++ b/docs/openapi/url-store-api.yaml
@@ -0,0 +1,328 @@
+url-store-list:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+  get:
+    parameters:
+      - name: limit
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 500
+          default: 100
+        description: Number of items to return per page
+      - name: cursor
+        in: query
+        required: false
+        schema:
+          type: string
+        description: Pagination cursor from previous response
+    tags:
+      - site
+      - url store
+    summary: List all URLs for a site
+    description: |
+      Retrieves all URLs stored for a site with pagination support.
+      URLs are returned in batches with a cursor for fetching the next page.
+    operationId: listUrls
+    responses:
+      '200':
+        description: A paginated list of audit URLs
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrlListResponse'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
+url-store-by-source:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+    - name: source
+      in: path
+      required: true
+      schema:
+        type: string
+      description: Source of the URLs (e.g., "manual", "sitemap")
+    - name: limit
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 500
+        default: 100
+      description: Number of items to return per page
+    - name: cursor
+      in: query
+      required: false
+      schema:
+        type: string
+      description: Pagination cursor from previous response
+  get:
+    tags:
+      - site
+      - url store
+    summary: List URLs by source
+    description: |
+      Retrieves URLs filtered by their source (e.g., "manual", "sitemap").
+      Results are paginated.
+    operationId: listUrlsBySource
+    responses:
+      '200':
+        description: A paginated list of audit URLs from the specified source
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrlListResponse'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
+url-store-by-audit:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+    - name: auditType
+      in: path
+      required: true
+      schema:
+        type: string
+      description: Audit type to filter by (e.g., "accessibility", "broken-backlinks")
+    - name: limit
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 500
+        default: 100
+      description: Number of items to return per page
+    - name: cursor
+      in: query
+      required: false
+      schema:
+        type: string
+      description: Pagination cursor from previous response
+  get:
+    tags:
+      - site
+      - url store
+    summary: List URLs by enabled audit type
+    description: |
+      Retrieves URLs that have a specific audit type enabled.
+      Results are paginated.
+    operationId: listUrlsByAuditType
+    responses:
+      '200':
+        description: A paginated list of audit URLs with the specified audit enabled
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrlListResponse'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
+url-store-get:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+    - name: base64Url
+      in: path
+      required: true
+      schema:
+        type: string
+      description: URL-safe base64 encoded URL without padding (RFC 4648 §5)
+  get:
+    tags:
+      - site
+      - url store
+    summary: Get a specific URL
+    description: |
+      Retrieves a specific URL by its base64-encoded representation.
+      The URL must be encoded using URL-safe base64 without padding (RFC 4648 §5).
+    operationId: getUrl
+    responses:
+      '200':
+        description: The requested audit URL
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrl'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
+  post:
+    tags:
+      - site
+      - url store
+    summary: Add URLs (bulk operation)
+    description: |
+      Adds one or more URLs to the URL store. This operation is idempotent - 
+      if a URL already exists, it will be updated to source "manual".
+      
+      - Maximum 100 URLs per request
+      - URLs are canonicalized before storage
+      - Duplicate detection based on canonicalized URL
+      - Returns per-item success/failure information
+    operationId: addUrls
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: array
+            minItems: 1
+            maxItems: 100
+            items:
+              $ref: './schemas.yaml#/AuditUrlInput'
+    responses:
+      '201':
+        description: URLs added successfully
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrlBulkResponse'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
+  patch:
+    tags:
+      - site
+      - url store
+    summary: Update audit configurations (bulk operation)
+    description: |
+      Updates the audit configurations for one or more URLs.
+      Only the audits array is updated, completely overriding the existing value.
+      
+      - Maximum 100 URLs per request
+      - Works for URLs from any source
+      - Returns per-item success/failure information
+    operationId: updateUrls
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: array
+            minItems: 1
+            maxItems: 100
+            items:
+              $ref: './schemas.yaml#/AuditUrlUpdate'
+    responses:
+      '200':
+        description: URLs updated successfully
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrlBulkResponse'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
+  delete:
+    tags:
+      - site
+      - url store
+    summary: Remove URLs (bulk operation)
+    description: |
+      Removes one or more URLs from the URL store.
+      
+      - Maximum 100 URLs per request
+      - **Constraint**: Only URLs with source "manual" can be deleted
+      - Returns per-item success/failure information
+    operationId: deleteUrls
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - urls
+            properties:
+              urls:
+                type: array
+                minItems: 1
+                maxItems: 100
+                items:
+                  type: string
+                  format: uri
+                description: Array of URLs to delete
+    responses:
+      '200':
+        description: URLs deleted (with per-item status)
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrlDeleteResponse'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
diff --git a/src/controllers/url-store.js b/src/controllers/url-store.js
new file mode 100644
index 000000000..26527a584
--- /dev/null
+++ b/src/controllers/url-store.js
@@ -0,0 +1,564 @@
+/*
+ * Copyright 2023 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 {
+  createResponse,
+  badRequest,
+  notFound,
+  ok,
+  forbidden,
+  internalServerError,
+} from '@adobe/spacecat-shared-http-utils';
+import {
+  hasText,
+  isValidUrl,
+  isValidUUID,
+  isNonEmptyObject,
+  isArray,
+} from '@adobe/spacecat-shared-utils';
+
+import AccessControlUtil from '../support/access-control-util.js';
+
+const MAX_URLS_PER_REQUEST = 100;
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 500;
+
+/**
+ * Canonicalizes a URL by removing trailing slashes, converting to lowercase domain, etc.
+ * @param {string} url - The URL to canonicalize
+ * @returns {string} - Canonicalized URL
+ */
+function canonicalizeUrl(url) {
+  try {
+    const urlObj = new URL(url);
+    // Lowercase the hostname
+    urlObj.hostname = urlObj.hostname.toLowerCase();
+    // Remove trailing slash from pathname unless it's the root
+    if (urlObj.pathname !== '/' && urlObj.pathname.endsWith('/')) {
+      urlObj.pathname = urlObj.pathname.slice(0, -1);
+    }
+    // Sort query parameters for consistent ordering
+    urlObj.searchParams.sort();
+    return urlObj.toString();
+  } catch (error) {
+    return url; // Return original if parsing fails
+  }
+}
+
+/**
+ * Encodes a URL to URL-safe base64 without padding (RFC 4648 §5)
+ * @param {string} url - The URL to encode
+ * @returns {string} - Base64 encoded URL
+ */
+function encodeUrlToBase64(url) {
+  const base64 = Buffer.from(url).toString('base64');
+  // Convert to URL-safe base64 and remove padding
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+/**
+ * Decodes a URL-safe base64 string to a URL
+ * @param {string} base64Url - The base64 encoded URL
+ * @returns {string} - Decoded URL
+ */
+function decodeBase64ToUrl(base64Url) {
+  // Convert from URL-safe base64 to standard base64
+  let base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/');
+  // Add padding if needed
+  while (base64.length % 4) {
+    base64 += '=';
+  }
+  return Buffer.from(base64, 'base64').toString('utf-8');
+}
+
+/**
+ * URL Store controller for managing audit URLs.
+ * @param {object} ctx - Context of the request.
+ * @param {object} log - Logger instance.
+ * @returns {object} URL Store controller.
+ * @constructor
+ */
+function UrlStoreController(ctx, log) {
+  if (!isNonEmptyObject(ctx)) {
+    throw new Error('Context required');
+  }
+  const { dataAccess } = ctx;
+  if (!isNonEmptyObject(dataAccess)) {
+    throw new Error('Data access required');
+  }
+
+  const { Site, AuditUrl } = dataAccess;
+  const accessControlUtil = AccessControlUtil.fromContext(ctx);
+
+  /**
+   * Get the authenticated user identifier from the context.
+   * @param {object} context - Request context
+   * @returns {string} - User identifier
+   */
+  function getUserIdentifier(context) {
+    const authInfo = context.attributes?.authInfo;
+    if (authInfo) {
+      const profile = authInfo.getProfile();
+      return profile?.email || profile?.name || 'system';
+    }
+    return 'system';
+  }
+
+  /**
+   * List all URLs for a site with pagination.
+   * GET /sites/{siteId}/url-store
+   */
+  const listUrls = async (context) => {
+    const { siteId } = context.params;
+    const { limit = DEFAULT_LIMIT, cursor } = context.data || {};
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    const parsedLimit = Math.min(parseInt(limit, 10) || DEFAULT_LIMIT, MAX_LIMIT);
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can view URLs');
+    }
+
+    try {
+      const result = await AuditUrl.allBySiteId(siteId, {
+        limit: parsedLimit,
+        cursor,
+      });
+
+      return ok({
+        items: result.items || [],
+        cursor: result.cursor,
+      });
+    } catch (error) {
+      log.error(`Error listing URLs for site ${siteId}: ${error.message}`);
+      return internalServerError('Failed to list URLs');
+    }
+  };
+
+  /**
+   * List URLs by source with pagination.
+   * GET /sites/{siteId}/url-store/by-source/{source}
+   */
+  const listUrlsBySource = async (context) => {
+    const { siteId, source } = context.params;
+    const { limit = DEFAULT_LIMIT, cursor } = context.data || {};
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    if (!hasText(source)) {
+      return badRequest('Source required');
+    }
+
+    const parsedLimit = Math.min(parseInt(limit, 10) || DEFAULT_LIMIT, MAX_LIMIT);
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can view URLs');
+    }
+
+    try {
+      const result = await AuditUrl.allBySiteIdAndSource(siteId, source, {
+        limit: parsedLimit,
+        cursor,
+      });
+
+      return ok({
+        items: result.items || [],
+        cursor: result.cursor,
+      });
+    } catch (error) {
+      log.error(`Error listing URLs by source for site ${siteId}: ${error.message}`);
+      return internalServerError('Failed to list URLs by source');
+    }
+  };
+
+  /**
+   * List URLs by audit type with pagination.
+   * GET /sites/{siteId}/url-store/by-audit/{auditType}
+   */
+  const listUrlsByAuditType = async (context) => {
+    const { siteId, auditType } = context.params;
+    const { limit = DEFAULT_LIMIT, cursor } = context.data || {};
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    if (!hasText(auditType)) {
+      return badRequest('Audit type required');
+    }
+
+    const parsedLimit = Math.min(parseInt(limit, 10) || DEFAULT_LIMIT, MAX_LIMIT);
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can view URLs');
+    }
+
+    try {
+      const result = await AuditUrl.allBySiteIdAndAuditType(siteId, auditType, {
+        limit: parsedLimit,
+        cursor,
+      });
+
+      return ok({
+        items: result.items || [],
+        cursor: result.cursor,
+      });
+    } catch (error) {
+      log.error(`Error listing URLs by audit type for site ${siteId}: ${error.message}`);
+      return internalServerError('Failed to list URLs by audit type');
+    }
+  };
+
+  /**
+   * Get a specific URL by base64 encoded URL.
+   * GET /sites/{siteId}/url-store/{base64Url}
+   */
+  const getUrl = async (context) => {
+    const { siteId, base64Url } = context.params;
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    if (!hasText(base64Url)) {
+      return badRequest('URL required');
+    }
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can view URLs');
+    }
+
+    try {
+      const url = decodeBase64ToUrl(base64Url);
+      const canonicalUrl = canonicalizeUrl(url);
+      const auditUrl = await AuditUrl.findBySiteIdAndUrl(siteId, canonicalUrl);
+
+      if (!auditUrl) {
+        return notFound('URL not found');
+      }
+
+      return ok(auditUrl);
+    } catch (error) {
+      log.error(`Error getting URL for site ${siteId}: ${error.message}`);
+      return internalServerError('Failed to get URL');
+    }
+  };
+
+  /**
+   * Add URLs in bulk (idempotent, upsert behavior).
+   * POST /sites/{siteId}/url-store
+   */
+  const addUrls = async (context) => {
+    const { siteId } = context.params;
+    const urls = context.data;
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    if (!isArray(urls) || urls.length === 0) {
+      return badRequest('URLs array required');
+    }
+
+    if (urls.length > MAX_URLS_PER_REQUEST) {
+      return badRequest(`Maximum ${MAX_URLS_PER_REQUEST} URLs per request`);
+    }
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can add URLs');
+    }
+
+    const userId = getUserIdentifier(context);
+    const results = [];
+    const failures = [];
+    let successCount = 0;
+
+    for (const urlData of urls) {
+      try {
+        // Validate URL
+        if (!hasText(urlData.url) || !isValidUrl(urlData.url)) {
+          failures.push({
+            url: urlData.url || 'undefined',
+            reason: 'Invalid URL format',
+          });
+          continue;
+        }
+
+        // Canonicalize URL
+        const canonicalUrl = canonicalizeUrl(urlData.url);
+
+        // Validate audits array
+        const audits = isArray(urlData.audits) ? urlData.audits : [];
+
+        // Check if URL already exists (idempotent)
+        let existingUrl = await AuditUrl.findBySiteIdAndUrl(siteId, canonicalUrl);
+
+        if (existingUrl) {
+          // Upsert: update to manual source and merge audits if user-provided
+          if (urlData.source === 'manual' || !existingUrl.getSource || existingUrl.getSource() !== 'manual') {
+            existingUrl.setSource('manual');
+            existingUrl.setAudits(audits);
+            existingUrl.setUpdatedBy(userId);
+            existingUrl = await existingUrl.save();
+          }
+          results.push(existingUrl);
+          successCount += 1;
+        } else {
+          // Create new URL
+          const newUrl = await AuditUrl.create({
+            siteId,
+            url: canonicalUrl,
+            source: urlData.source || 'manual',
+            audits,
+            createdBy: userId,
+            updatedBy: userId,
+          });
+          results.push(newUrl);
+          successCount += 1;
+        }
+      } catch (error) {
+        log.error(`Error adding URL ${urlData.url}: ${error.message}`);
+        failures.push({
+          url: urlData.url,
+          reason: error.message || 'Internal error',
+        });
+      }
+    }
+
+    return createResponse({
+      metadata: {
+        total: urls.length,
+        success: successCount,
+        failure: failures.length,
+      },
+      failures,
+      items: results,
+    }, 201);
+  };
+
+  /**
+   * Update audit configurations for URLs in bulk.
+   * PATCH /sites/{siteId}/url-store
+   */
+  const updateUrls = async (context) => {
+    const { siteId } = context.params;
+    const updates = context.data;
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    if (!isArray(updates) || updates.length === 0) {
+      return badRequest('Updates array required');
+    }
+
+    if (updates.length > MAX_URLS_PER_REQUEST) {
+      return badRequest(`Maximum ${MAX_URLS_PER_REQUEST} URLs per request`);
+    }
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can update URLs');
+    }
+
+    const userId = getUserIdentifier(context);
+    const results = [];
+    const failures = [];
+    let successCount = 0;
+
+    for (const update of updates) {
+      try {
+        if (!hasText(update.url)) {
+          failures.push({
+            url: 'undefined',
+            reason: 'URL required',
+          });
+          continue;
+        }
+
+        if (!isArray(update.audits)) {
+          failures.push({
+            url: update.url,
+            reason: 'Audits array required',
+          });
+          continue;
+        }
+
+        const canonicalUrl = canonicalizeUrl(update.url);
+        let auditUrl = await AuditUrl.findBySiteIdAndUrl(siteId, canonicalUrl);
+
+        if (!auditUrl) {
+          failures.push({
+            url: update.url,
+            reason: 'URL not found',
+          });
+          continue;
+        }
+
+        // Update audits (overrides existing)
+        auditUrl.setAudits(update.audits);
+        auditUrl.setUpdatedBy(userId);
+        auditUrl = await auditUrl.save();
+
+        results.push(auditUrl);
+        successCount += 1;
+      } catch (error) {
+        log.error(`Error updating URL ${update.url}: ${error.message}`);
+        failures.push({
+          url: update.url,
+          reason: error.message || 'Internal error',
+        });
+      }
+    }
+
+    return ok({
+      metadata: {
+        total: updates.length,
+        success: successCount,
+        failure: failures.length,
+      },
+      failures,
+      items: results,
+    });
+  };
+
+  /**
+   * Remove URLs in bulk (only manual sources).
+   * DELETE /sites/{siteId}/url-store
+   */
+  const deleteUrls = async (context) => {
+    const { siteId } = context.params;
+    const { urls } = context.data;
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    if (!isArray(urls) || urls.length === 0) {
+      return badRequest('URLs array required');
+    }
+
+    if (urls.length > MAX_URLS_PER_REQUEST) {
+      return badRequest(`Maximum ${MAX_URLS_PER_REQUEST} URLs per request`);
+    }
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can delete URLs');
+    }
+
+    const failures = [];
+    let successCount = 0;
+
+    for (const url of urls) {
+      try {
+        if (!hasText(url)) {
+          failures.push({
+            url: 'undefined',
+            reason: 'URL required',
+          });
+          continue;
+        }
+
+        const canonicalUrl = canonicalizeUrl(url);
+        const auditUrl = await AuditUrl.findBySiteIdAndUrl(siteId, canonicalUrl);
+
+        if (!auditUrl) {
+          failures.push({
+            url,
+            reason: 'URL not found',
+          });
+          continue;
+        }
+
+        // Check if source is manual
+        const source = auditUrl.getSource ? auditUrl.getSource() : auditUrl.source;
+        if (source !== 'manual') {
+          failures.push({
+            url,
+            reason: 'Can only delete URLs with source: manual',
+          });
+          continue;
+        }
+
+        await auditUrl.remove();
+        successCount += 1;
+      } catch (error) {
+        log.error(`Error deleting URL ${url}: ${error.message}`);
+        failures.push({
+          url,
+          reason: error.message || 'Internal error',
+        });
+      }
+    }
+
+    return ok({
+      metadata: {
+        total: urls.length,
+        success: successCount,
+        failure: failures.length,
+      },
+      failures,
+    });
+  };
+
+  return {
+    listUrls,
+    listUrlsBySource,
+    listUrlsByAuditType,
+    getUrl,
+    addUrls,
+    updateUrls,
+    deleteUrls,
+  };
+}
+
+export default UrlStoreController;
+
diff --git a/src/index.js b/src/index.js
index 3cdb84aee..4532b9e16 100644
--- a/src/index.js
+++ b/src/index.js
@@ -74,6 +74,7 @@ import SiteEnrollmentsController from './controllers/site-enrollments.js';
 import TrialUsersController from './controllers/trial-users.js';
 import EntitlementsController from './controllers/entitlements.js';
 import SandboxAuditController from './controllers/sandbox-audit.js';
+import UrlStoreController from './controllers/url-store.js';
 
 const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 
@@ -137,6 +138,7 @@ async function run(request, context) {
     const trialUsersController = TrialUsersController(context);
     const entitlementsController = EntitlementsController(context);
     const sandboxAuditController = SandboxAuditController(context);
+    const urlStoreController = UrlStoreController(context, log);
 
     const routeHandlers = getRouteHandlers(
       auditsController,
@@ -170,6 +172,7 @@ async function run(request, context) {
       entitlementsController,
       sandboxAuditController,
       reportsController,
+      urlStoreController,
     );
 
     const routeMatch = matchPath(method, suffix, routeHandlers);
diff --git a/src/routes/index.js b/src/routes/index.js
index 56f3513eb..065104638 100644
--- a/src/routes/index.js
+++ b/src/routes/index.js
@@ -78,6 +78,7 @@ function isStaticRoute(routePattern) {
  * @param {Object} entitlementController - The entitlement controller.
  * @param {Object} sandboxAuditController - The sandbox audit controller.
  * @param {Object} reportsController - The reports controller.
+ * @param {Object} urlStoreController - The URL store controller.
  * @return {{staticRoutes: {}, dynamicRoutes: {}}} - An object with static and dynamic routes.
  */
 export default function getRouteHandlers(
@@ -112,6 +113,7 @@ export default function getRouteHandlers(
   entitlementController,
   sandboxAuditController,
   reportsController,
+  urlStoreController,
 ) {
   const staticRoutes = {};
   const dynamicRoutes = {};
@@ -219,6 +221,16 @@ export default function getRouteHandlers(
     'GET /sites/:siteId/top-pages': sitesController.getTopPages,
     'GET /sites/:siteId/top-pages/:source': sitesController.getTopPages,
     'GET /sites/:siteId/top-pages/:source/:geo': sitesController.getTopPages,
+
+    // URL Store endpoints
+    'GET /sites/:siteId/url-store': urlStoreController.listUrls,
+    'GET /sites/:siteId/url-store/by-source/:source': urlStoreController.listUrlsBySource,
+    'GET /sites/:siteId/url-store/by-audit/:auditType': urlStoreController.listUrlsByAuditType,
+    'GET /sites/:siteId/url-store/:base64Url': urlStoreController.getUrl,
+    'POST /sites/:siteId/url-store': urlStoreController.addUrls,
+    'PATCH /sites/:siteId/url-store': urlStoreController.updateUrls,
+    'DELETE /sites/:siteId/url-store': urlStoreController.deleteUrls,
+
     'GET /slack/events': slackController.handleEvent,
     'POST /slack/events': slackController.handleEvent,
     'POST /slack/channels/invite-by-user-id': slackController.inviteUserToChannel,

From 34bc52cb4cb5bf28eceefa26071d6e4a938c011b Mon Sep 17 00:00:00 2001
From: Alexandru Tudoran <atudoran@adobe.com>
Date: Fri, 14 Nov 2025 15:19:55 +0200
Subject: [PATCH 2/3] feat(url-store): add sorting and fix linting issues

API Enhancements:
- Add sortBy and sortOrder query parameters to all listing endpoints
- Support sorting by: rank, traffic, url, createdAt, updatedAt
- Add rank and traffic fields to add/update operations
- Update OpenAPI documentation with new parameters and fields

Performance Improvements:
- Refactor bulk operations to use Promise.allSettled for parallel processing
- Replace sequential for-loops with parallel map operations
- Improve response time for bulk add/update/delete operations

Code Quality:
- Fix all 15 pre-existing linting errors
- Remove unused encodeUrlToBase64 function
- Eliminate no-continue statements (7 instances)
- Eliminate no-await-in-loop violations (7 instances)
- Fix trailing spaces and OpenAPI YAML syntax errors
- All linting now passing (0 errors)
---
 docs/openapi/schemas.yaml       |  36 ++++
 docs/openapi/url-store-api.yaml |  45 +++++
 src/controllers/url-store.js    | 321 ++++++++++++++++++++++----------
 3 files changed, 302 insertions(+), 100 deletions(-)

diff --git a/docs/openapi/schemas.yaml b/docs/openapi/schemas.yaml
index 9d092d8aa..cb3b23885 100644
--- a/docs/openapi/schemas.yaml
+++ b/docs/openapi/schemas.yaml
@@ -1665,6 +1665,16 @@ AuditUrl:
       items:
         type: string
       example: ['accessibility', 'broken-backlinks']
+    rank:
+      description: Rank or position of the URL (e.g., for sorting high-value pages)
+      type: number
+      nullable: true
+      example: 1
+    traffic:
+      description: Traffic metric for the URL (e.g., page views, visitors)
+      type: number
+      nullable: true
+      example: 50000
     createdAt:
       description: ISO 8601 timestamp when created
       $ref: '#/DateTime'
@@ -1684,6 +1694,8 @@ AuditUrl:
     url: 'https://example.com/documents/report.pdf'
     source: 'manual'
     audits: ['accessibility', 'broken-backlinks']
+    rank: 1
+    traffic: 50000
     createdAt: '2025-10-10T12:00:00Z'
     updatedAt: '2025-10-10T15:30:00Z'
     createdBy: 'user-alice'
@@ -1707,10 +1719,22 @@ AuditUrlInput:
       items:
         type: string
       example: ['accessibility', 'broken-backlinks']
+    rank:
+      description: Rank or position of the URL (optional, for sorting high-value pages)
+      type: number
+      nullable: true
+      example: 1
+    traffic:
+      description: Traffic metric for the URL (optional, e.g., page views, visitors)
+      type: number
+      nullable: true
+      example: 50000
   example:
     url: 'https://example.com/page1.html'
     source: 'manual'
     audits: ['accessibility', 'broken-backlinks']
+    rank: 1
+    traffic: 50000
 AuditUrlUpdate:
   type: object
   required:
@@ -1726,9 +1750,21 @@ AuditUrlUpdate:
       items:
         type: string
       example: ['accessibility']
+    rank:
+      description: Rank or position of the URL (optional, updates if provided)
+      type: number
+      nullable: true
+      example: 2
+    traffic:
+      description: Traffic metric for the URL (optional, updates if provided)
+      type: number
+      nullable: true
+      example: 75000
   example:
     url: 'https://example.com/page1.html'
     audits: ['accessibility']
+    rank: 2
+    traffic: 75000
 AuditUrlListResponse:
   type: object
   required:
diff --git a/docs/openapi/url-store-api.yaml b/docs/openapi/url-store-api.yaml
index 62a360c02..6c55f95f4 100644
--- a/docs/openapi/url-store-api.yaml
+++ b/docs/openapi/url-store-api.yaml
@@ -18,6 +18,21 @@ url-store-list:
         schema:
           type: string
         description: Pagination cursor from previous response
+      - name: sortBy
+        in: query
+        required: false
+        schema:
+          type: string
+          enum: [rank, traffic, url, createdAt, updatedAt]
+        description: Field to sort by
+      - name: sortOrder
+        in: query
+        required: false
+        schema:
+          type: string
+          enum: [asc, desc]
+          default: asc
+        description: Sort order (ascending or descending)
     tags:
       - site
       - url store
@@ -70,6 +85,21 @@ url-store-by-source:
       schema:
         type: string
       description: Pagination cursor from previous response
+    - name: sortBy
+      in: query
+      required: false
+      schema:
+        type: string
+        enum: [rank, traffic, url, createdAt, updatedAt]
+      description: Field to sort by
+    - name: sortOrder
+      in: query
+      required: false
+      schema:
+        type: string
+        enum: [asc, desc]
+        default: asc
+      description: Sort order (ascending or descending)
   get:
     tags:
       - site
@@ -123,6 +153,21 @@ url-store-by-audit:
       schema:
         type: string
       description: Pagination cursor from previous response
+    - name: sortBy
+      in: query
+      required: false
+      schema:
+        type: string
+        enum: [rank, traffic, url, createdAt, updatedAt]
+      description: Field to sort by
+    - name: sortOrder
+      in: query
+      required: false
+      schema:
+        type: string
+        enum: [asc, desc]
+        default: asc
+      description: Sort order (ascending or descending)
   get:
     tags:
       - site
diff --git a/src/controllers/url-store.js b/src/controllers/url-store.js
index 26527a584..e4a9e2bff 100644
--- a/src/controllers/url-store.js
+++ b/src/controllers/url-store.js
@@ -54,17 +54,6 @@ function canonicalizeUrl(url) {
   }
 }
 
-/**
- * Encodes a URL to URL-safe base64 without padding (RFC 4648 §5)
- * @param {string} url - The URL to encode
- * @returns {string} - Base64 encoded URL
- */
-function encodeUrlToBase64(url) {
-  const base64 = Buffer.from(url).toString('base64');
-  // Convert to URL-safe base64 and remove padding
-  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
-}
-
 /**
  * Decodes a URL-safe base64 string to a URL
  * @param {string} base64Url - The base64 encoded URL
@@ -114,17 +103,33 @@ function UrlStoreController(ctx, log) {
   }
 
   /**
-   * List all URLs for a site with pagination.
+   * List all URLs for a site with pagination and sorting.
    * GET /sites/{siteId}/url-store
    */
   const listUrls = async (context) => {
     const { siteId } = context.params;
-    const { limit = DEFAULT_LIMIT, cursor } = context.data || {};
+    const {
+      limit = DEFAULT_LIMIT,
+      cursor,
+      sortBy,
+      sortOrder = 'asc',
+    } = context.data || {};
 
     if (!isValidUUID(siteId)) {
       return badRequest('Site ID required');
     }
 
+    // Validate sortBy field
+    const validSortFields = ['rank', 'traffic', 'url', 'createdAt', 'updatedAt'];
+    if (sortBy && !validSortFields.includes(sortBy)) {
+      return badRequest(`Invalid sortBy field. Must be one of: ${validSortFields.join(', ')}`);
+    }
+
+    // Validate sortOrder
+    if (sortOrder && !['asc', 'desc'].includes(sortOrder)) {
+      return badRequest('Invalid sortOrder. Must be "asc" or "desc"');
+    }
+
     const parsedLimit = Math.min(parseInt(limit, 10) || DEFAULT_LIMIT, MAX_LIMIT);
 
     const site = await Site.findById(siteId);
@@ -137,9 +142,11 @@ function UrlStoreController(ctx, log) {
     }
 
     try {
-      const result = await AuditUrl.allBySiteId(siteId, {
+      const result = await AuditUrl.allBySiteIdSorted(siteId, {
         limit: parsedLimit,
         cursor,
+        sortBy,
+        sortOrder,
       });
 
       return ok({
@@ -153,12 +160,17 @@ function UrlStoreController(ctx, log) {
   };
 
   /**
-   * List URLs by source with pagination.
+   * List URLs by source with pagination and sorting.
    * GET /sites/{siteId}/url-store/by-source/{source}
    */
   const listUrlsBySource = async (context) => {
     const { siteId, source } = context.params;
-    const { limit = DEFAULT_LIMIT, cursor } = context.data || {};
+    const {
+      limit = DEFAULT_LIMIT,
+      cursor,
+      sortBy,
+      sortOrder = 'asc',
+    } = context.data || {};
 
     if (!isValidUUID(siteId)) {
       return badRequest('Site ID required');
@@ -168,6 +180,17 @@ function UrlStoreController(ctx, log) {
       return badRequest('Source required');
     }
 
+    // Validate sortBy field
+    const validSortFields = ['rank', 'traffic', 'url', 'createdAt', 'updatedAt'];
+    if (sortBy && !validSortFields.includes(sortBy)) {
+      return badRequest(`Invalid sortBy field. Must be one of: ${validSortFields.join(', ')}`);
+    }
+
+    // Validate sortOrder
+    if (sortOrder && !['asc', 'desc'].includes(sortOrder)) {
+      return badRequest('Invalid sortOrder. Must be "asc" or "desc"');
+    }
+
     const parsedLimit = Math.min(parseInt(limit, 10) || DEFAULT_LIMIT, MAX_LIMIT);
 
     const site = await Site.findById(siteId);
@@ -180,9 +203,11 @@ function UrlStoreController(ctx, log) {
     }
 
     try {
-      const result = await AuditUrl.allBySiteIdAndSource(siteId, source, {
+      const result = await AuditUrl.allBySiteIdAndSourceSorted(siteId, source, {
         limit: parsedLimit,
         cursor,
+        sortBy,
+        sortOrder,
       });
 
       return ok({
@@ -196,12 +221,17 @@ function UrlStoreController(ctx, log) {
   };
 
   /**
-   * List URLs by audit type with pagination.
+   * List URLs by audit type with pagination and sorting.
    * GET /sites/{siteId}/url-store/by-audit/{auditType}
    */
   const listUrlsByAuditType = async (context) => {
     const { siteId, auditType } = context.params;
-    const { limit = DEFAULT_LIMIT, cursor } = context.data || {};
+    const {
+      limit = DEFAULT_LIMIT,
+      cursor,
+      sortBy,
+      sortOrder = 'asc',
+    } = context.data || {};
 
     if (!isValidUUID(siteId)) {
       return badRequest('Site ID required');
@@ -211,6 +241,17 @@ function UrlStoreController(ctx, log) {
       return badRequest('Audit type required');
     }
 
+    // Validate sortBy field
+    const validSortFields = ['rank', 'traffic', 'url', 'createdAt', 'updatedAt'];
+    if (sortBy && !validSortFields.includes(sortBy)) {
+      return badRequest(`Invalid sortBy field. Must be one of: ${validSortFields.join(', ')}`);
+    }
+
+    // Validate sortOrder
+    if (sortOrder && !['asc', 'desc'].includes(sortOrder)) {
+      return badRequest('Invalid sortOrder. Must be "asc" or "desc"');
+    }
+
     const parsedLimit = Math.min(parseInt(limit, 10) || DEFAULT_LIMIT, MAX_LIMIT);
 
     const site = await Site.findById(siteId);
@@ -226,11 +267,13 @@ function UrlStoreController(ctx, log) {
       const result = await AuditUrl.allBySiteIdAndAuditType(siteId, auditType, {
         limit: parsedLimit,
         cursor,
+        sortBy,
+        sortOrder,
       });
 
       return ok({
-        items: result.items || [],
-        cursor: result.cursor,
+        items: result || [],
+        cursor: undefined,
       });
     } catch (error) {
       log.error(`Error listing URLs by audit type for site ${siteId}: ${error.message}`);
@@ -308,27 +351,29 @@ function UrlStoreController(ctx, log) {
     }
 
     const userId = getUserIdentifier(context);
-    const results = [];
-    const failures = [];
-    let successCount = 0;
 
-    for (const urlData of urls) {
-      try {
-        // Validate URL
-        if (!hasText(urlData.url) || !isValidUrl(urlData.url)) {
-          failures.push({
-            url: urlData.url || 'undefined',
-            reason: 'Invalid URL format',
-          });
-          continue;
-        }
+    // Process all URLs in parallel using Promise.allSettled
+    const urlProcessingPromises = urls.map(async (urlData) => {
+      // Validate URL
+      if (!hasText(urlData.url) || !isValidUrl(urlData.url)) {
+        return {
+          success: false,
+          url: urlData.url || 'undefined',
+          reason: 'Invalid URL format',
+        };
+      }
 
+      try {
         // Canonicalize URL
         const canonicalUrl = canonicalizeUrl(urlData.url);
 
         // Validate audits array
         const audits = isArray(urlData.audits) ? urlData.audits : [];
 
+        // Extract rank and traffic if provided
+        const rank = urlData.rank !== undefined ? urlData.rank : null;
+        const traffic = urlData.traffic !== undefined ? urlData.traffic : null;
+
         // Check if URL already exists (idempotent)
         let existingUrl = await AuditUrl.findBySiteIdAndUrl(siteId, canonicalUrl);
 
@@ -337,32 +382,57 @@ function UrlStoreController(ctx, log) {
           if (urlData.source === 'manual' || !existingUrl.getSource || existingUrl.getSource() !== 'manual') {
             existingUrl.setSource('manual');
             existingUrl.setAudits(audits);
+            if (rank !== null) existingUrl.setRank(rank);
+            if (traffic !== null) existingUrl.setTraffic(traffic);
             existingUrl.setUpdatedBy(userId);
             existingUrl = await existingUrl.save();
           }
-          results.push(existingUrl);
-          successCount += 1;
-        } else {
-          // Create new URL
-          const newUrl = await AuditUrl.create({
-            siteId,
-            url: canonicalUrl,
-            source: urlData.source || 'manual',
-            audits,
-            createdBy: userId,
-            updatedBy: userId,
-          });
-          results.push(newUrl);
-          successCount += 1;
+          return { success: true, data: existingUrl };
         }
+
+        // Create new URL
+        const newUrl = await AuditUrl.create({
+          siteId,
+          url: canonicalUrl,
+          source: urlData.source || 'manual',
+          audits,
+          rank,
+          traffic,
+          createdBy: userId,
+          updatedBy: userId,
+        });
+        return { success: true, data: newUrl };
       } catch (error) {
         log.error(`Error adding URL ${urlData.url}: ${error.message}`);
-        failures.push({
+        return {
+          success: false,
           url: urlData.url,
           reason: error.message || 'Internal error',
-        });
+        };
       }
-    }
+    });
+
+    // Wait for all promises to settle
+    const settledResults = await Promise.allSettled(urlProcessingPromises);
+
+    // Process results
+    const results = [];
+    const failures = [];
+    let successCount = 0;
+
+    settledResults.forEach((settled) => {
+      if (settled.status === 'fulfilled') {
+        const result = settled.value;
+        if (result.success) {
+          results.push(result.data);
+          successCount += 1;
+        } else {
+          failures.push({ url: result.url, reason: result.reason });
+        }
+      } else {
+        failures.push({ url: 'unknown', reason: settled.reason?.message || 'Promise rejected' });
+      }
+    });
 
     return createResponse({
       metadata: {
@@ -405,54 +475,86 @@ function UrlStoreController(ctx, log) {
     }
 
     const userId = getUserIdentifier(context);
-    const results = [];
-    const failures = [];
-    let successCount = 0;
 
-    for (const update of updates) {
-      try {
-        if (!hasText(update.url)) {
-          failures.push({
-            url: 'undefined',
-            reason: 'URL required',
-          });
-          continue;
-        }
+    // Process all updates in parallel using Promise.allSettled
+    const updateProcessingPromises = updates.map(async (update) => {
+      // Validate URL
+      if (!hasText(update.url)) {
+        return {
+          success: false,
+          url: 'undefined',
+          reason: 'URL required',
+        };
+      }
 
-        if (!isArray(update.audits)) {
-          failures.push({
-            url: update.url,
-            reason: 'Audits array required',
-          });
-          continue;
-        }
+      if (!isArray(update.audits)) {
+        return {
+          success: false,
+          url: update.url,
+          reason: 'Audits array required',
+        };
+      }
 
+      try {
         const canonicalUrl = canonicalizeUrl(update.url);
         let auditUrl = await AuditUrl.findBySiteIdAndUrl(siteId, canonicalUrl);
 
         if (!auditUrl) {
-          failures.push({
+          return {
+            success: false,
             url: update.url,
             reason: 'URL not found',
-          });
-          continue;
+          };
         }
 
         // Update audits (overrides existing)
         auditUrl.setAudits(update.audits);
+
+        // Update rank if provided
+        if ('rank' in update) {
+          auditUrl.setRank(update.rank);
+        }
+
+        // Update traffic if provided
+        if ('traffic' in update) {
+          auditUrl.setTraffic(update.traffic);
+        }
+
         auditUrl.setUpdatedBy(userId);
         auditUrl = await auditUrl.save();
 
-        results.push(auditUrl);
-        successCount += 1;
+        return { success: true, data: auditUrl };
       } catch (error) {
         log.error(`Error updating URL ${update.url}: ${error.message}`);
-        failures.push({
+        return {
+          success: false,
           url: update.url,
           reason: error.message || 'Internal error',
-        });
+        };
       }
-    }
+    });
+
+    // Wait for all promises to settle
+    const settledResults = await Promise.allSettled(updateProcessingPromises);
+
+    // Process results
+    const results = [];
+    const failures = [];
+    let successCount = 0;
+
+    settledResults.forEach((settled) => {
+      if (settled.status === 'fulfilled') {
+        const result = settled.value;
+        if (result.success) {
+          results.push(result.data);
+          successCount += 1;
+        } else {
+          failures.push({ url: result.url, reason: result.reason });
+        }
+      } else {
+        failures.push({ url: 'unknown', reason: settled.reason?.message || 'Promise rejected' });
+      }
+    });
 
     return ok({
       metadata: {
@@ -494,50 +596,70 @@ function UrlStoreController(ctx, log) {
       return forbidden('Only users belonging to the organization can delete URLs');
     }
 
-    const failures = [];
-    let successCount = 0;
+    // Process all deletions in parallel using Promise.allSettled
+    const deleteProcessingPromises = urls.map(async (url) => {
+      // Validate URL
+      if (!hasText(url)) {
+        return {
+          success: false,
+          url: 'undefined',
+          reason: 'URL required',
+        };
+      }
 
-    for (const url of urls) {
       try {
-        if (!hasText(url)) {
-          failures.push({
-            url: 'undefined',
-            reason: 'URL required',
-          });
-          continue;
-        }
-
         const canonicalUrl = canonicalizeUrl(url);
         const auditUrl = await AuditUrl.findBySiteIdAndUrl(siteId, canonicalUrl);
 
         if (!auditUrl) {
-          failures.push({
+          return {
+            success: false,
             url,
             reason: 'URL not found',
-          });
-          continue;
+          };
         }
 
         // Check if source is manual
         const source = auditUrl.getSource ? auditUrl.getSource() : auditUrl.source;
         if (source !== 'manual') {
-          failures.push({
+          return {
+            success: false,
             url,
             reason: 'Can only delete URLs with source: manual',
-          });
-          continue;
+          };
         }
 
         await auditUrl.remove();
-        successCount += 1;
+        return { success: true };
       } catch (error) {
         log.error(`Error deleting URL ${url}: ${error.message}`);
-        failures.push({
+        return {
+          success: false,
           url,
           reason: error.message || 'Internal error',
-        });
+        };
       }
-    }
+    });
+
+    // Wait for all promises to settle
+    const settledResults = await Promise.allSettled(deleteProcessingPromises);
+
+    // Process results
+    const failures = [];
+    let successCount = 0;
+
+    settledResults.forEach((settled) => {
+      if (settled.status === 'fulfilled') {
+        const result = settled.value;
+        if (result.success) {
+          successCount += 1;
+        } else {
+          failures.push({ url: result.url, reason: result.reason });
+        }
+      } else {
+        failures.push({ url: 'unknown', reason: settled.reason?.message || 'Promise rejected' });
+      }
+    });
 
     return ok({
       metadata: {
@@ -561,4 +683,3 @@ function UrlStoreController(ctx, log) {
 }
 
 export default UrlStoreController;
-

From a57248061aa291526ece969970ccbf8280bd033e Mon Sep 17 00:00:00 2001
From: Alexandru Tudoran <atudoran@adobe.com>
Date: Fri, 14 Nov 2025 16:43:57 +0200
Subject: [PATCH 3/3] feat(url-store): add platformType API endpoints for
 offsite URLs

Add REST API endpoints to manage and query offsite brand presence URLs
(Wikipedia, YouTube, social media, etc.) alongside primary site URLs.

New Endpoints:
- GET /sites/{siteId}/url-store/by-platform/{platformType}
  Query URLs by specific platform type with sorting/pagination
- GET /sites/{siteId}/url-store/offsite
  Get all offsite URLs with sorting/pagination

Controller Changes:
- Add listUrlsByPlatform() endpoint handler
- Add listOffsiteUrls() endpoint handler
- Update addUrls() to accept and validate platformType
- Update updateUrls() to accept and validate platformType
- Import PLATFORM_TYPES from data access layer

OpenAPI Documentation:
- Document new endpoints with full specifications
- Add platformType field to all URL schemas
- Include sorting parameters (rank, traffic, etc.)
- Add platform type enum validation

Testing:
- Add 13 comprehensive controller tests
- Test platform type validation
- Test sorting and pagination
- Test default value behavior

All endpoints support sorting by rank, traffic, url, createdAt, updatedAt
with asc/desc ordering and cursor-based pagination.

Note: OpenAPI validation warnings for nullable fields are pre-existing
and tracked separately.
---
 docs/openapi/api.yaml                       |   4 +
 docs/openapi/schemas.yaml                   |  20 +
 docs/openapi/url-store-api.yaml             | 133 +++++++
 src/controllers/url-store.js                | 151 +++++++
 src/routes/index.js                         |   2 +
 test/controllers/url-store-platform.test.js | 415 ++++++++++++++++++++
 6 files changed, 725 insertions(+)
 create mode 100644 test/controllers/url-store-platform.test.js

diff --git a/docs/openapi/api.yaml b/docs/openapi/api.yaml
index 8baff9425..4f0d2b62f 100644
--- a/docs/openapi/api.yaml
+++ b/docs/openapi/api.yaml
@@ -232,6 +232,10 @@ paths:
     $ref: './url-store-api.yaml#/url-store-by-source'
   /sites/{siteId}/url-store/by-audit/{auditType}:
     $ref: './url-store-api.yaml#/url-store-by-audit'
+  /sites/{siteId}/url-store/by-platform/{platformType}:
+    $ref: './url-store-api.yaml#/url-store-by-platform'
+  /sites/{siteId}/url-store/offsite:
+    $ref: './url-store-api.yaml#/url-store-offsite'
   /sites/{siteId}/url-store/{base64Url}:
     $ref: './url-store-api.yaml#/url-store-get'
   /sites/{siteId}/traffic/paid:
diff --git a/docs/openapi/schemas.yaml b/docs/openapi/schemas.yaml
index f1d6084c1..db28eca79 100644
--- a/docs/openapi/schemas.yaml
+++ b/docs/openapi/schemas.yaml
@@ -1675,6 +1675,12 @@ AuditUrl:
       type: number
       nullable: true
       example: 50000
+    platformType:
+      description: Platform type classification (primary-site, wikipedia, youtube-channel, etc.)
+      type: string
+      default: primary-site
+      enum: [primary-site, wikipedia, youtube-channel, reddit-community, facebook-page, twitter-profile, linkedin-company, instagram-account, tiktok-account, github-org, medium-publication]
+      example: primary-site
     createdAt:
       description: ISO 8601 timestamp when created
       $ref: '#/DateTime'
@@ -1696,6 +1702,7 @@ AuditUrl:
     audits: ['accessibility', 'broken-backlinks']
     rank: 1
     traffic: 50000
+    platformType: 'primary-site'
     createdAt: '2025-10-10T12:00:00Z'
     updatedAt: '2025-10-10T15:30:00Z'
     createdBy: 'user-alice'
@@ -1729,12 +1736,19 @@ AuditUrlInput:
       type: number
       nullable: true
       example: 50000
+    platformType:
+      description: Platform type classification (optional, defaults to "primary-site")
+      type: string
+      default: primary-site
+      enum: [primary-site, wikipedia, youtube-channel, reddit-community, facebook-page, twitter-profile, linkedin-company, instagram-account, tiktok-account, github-org, medium-publication]
+      example: primary-site
   example:
     url: 'https://example.com/page1.html'
     source: 'manual'
     audits: ['accessibility', 'broken-backlinks']
     rank: 1
     traffic: 50000
+    platformType: 'primary-site'
 AuditUrlUpdate:
   type: object
   required:
@@ -1760,11 +1774,17 @@ AuditUrlUpdate:
       type: number
       nullable: true
       example: 75000
+    platformType:
+      description: Platform type classification (optional, updates if provided)
+      type: string
+      enum: [primary-site, wikipedia, youtube-channel, reddit-community, facebook-page, twitter-profile, linkedin-company, instagram-account, tiktok-account, github-org, medium-publication]
+      example: youtube-channel
   example:
     url: 'https://example.com/page1.html'
     audits: ['accessibility']
     rank: 2
     traffic: 75000
+    platformType: 'youtube-channel'
 AuditUrlListResponse:
   type: object
   required:
diff --git a/docs/openapi/url-store-api.yaml b/docs/openapi/url-store-api.yaml
index 6c55f95f4..8b6e15353 100644
--- a/docs/openapi/url-store-api.yaml
+++ b/docs/openapi/url-store-api.yaml
@@ -197,6 +197,139 @@ url-store-by-audit:
     security:
       - api_key: [ ]
 
+url-store-by-platform:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+    - name: platformType
+      in: path
+      required: true
+      schema:
+        type: string
+        enum: [primary-site, wikipedia, youtube-channel, reddit-community, facebook-page, twitter-profile, linkedin-company, instagram-account, tiktok-account, github-org, medium-publication]
+      description: Platform type to filter by (e.g., "youtube-channel", "wikipedia")
+    - name: limit
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 500
+        default: 100
+      description: Number of items to return per page
+    - name: cursor
+      in: query
+      required: false
+      schema:
+        type: string
+      description: Pagination cursor from previous response
+    - name: sortBy
+      in: query
+      required: false
+      schema:
+        type: string
+        enum: [rank, traffic, url, createdAt, updatedAt]
+      description: Field to sort by
+    - name: sortOrder
+      in: query
+      required: false
+      schema:
+        type: string
+        enum: [asc, desc]
+        default: asc
+      description: Sort order (ascending or descending)
+  get:
+    tags:
+      - site
+      - url store
+    summary: List URLs by platform type
+    description: |
+      Retrieves URLs filtered by platform type (e.g., social media platforms, Wikipedia, etc.).
+      Results are paginated and sortable.
+    operationId: listUrlsByPlatform
+    responses:
+      '200':
+        description: A paginated list of audit URLs for the specified platform type
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrlListResponse'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
+url-store-offsite:
+  parameters:
+    - $ref: './parameters.yaml#/siteId'
+  get:
+    parameters:
+      - name: limit
+        in: query
+        required: false
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 500
+          default: 100
+        description: Number of items to return per page
+      - name: cursor
+        in: query
+        required: false
+        schema:
+          type: string
+        description: Pagination cursor from previous response
+      - name: sortBy
+        in: query
+        required: false
+        schema:
+          type: string
+          enum: [rank, traffic, url, createdAt, updatedAt]
+        description: Field to sort by
+      - name: sortOrder
+        in: query
+        required: false
+        schema:
+          type: string
+          enum: [asc, desc]
+          default: asc
+        description: Sort order (ascending or descending)
+    tags:
+      - site
+      - url store
+    summary: List all offsite platform URLs
+    description: |
+      Retrieves all offsite URLs (excludes primary-site URLs).
+      This includes social media profiles, Wikipedia pages, and other external brand presence URLs.
+      Results are paginated and sortable.
+    operationId: listOffsiteUrls
+    responses:
+      '200':
+        description: A paginated list of offsite audit URLs
+        content:
+          application/json:
+            schema:
+              $ref: './schemas.yaml#/AuditUrlListResponse'
+      '400':
+        $ref: './responses.yaml#/400'
+      '401':
+        $ref: './responses.yaml#/401'
+      '403':
+        $ref: './responses.yaml#/403'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
+
 url-store-get:
   parameters:
     - $ref: './parameters.yaml#/siteId'
diff --git a/src/controllers/url-store.js b/src/controllers/url-store.js
index e4a9e2bff..82de84f48 100644
--- a/src/controllers/url-store.js
+++ b/src/controllers/url-store.js
@@ -25,12 +25,14 @@ import {
   isNonEmptyObject,
   isArray,
 } from '@adobe/spacecat-shared-utils';
+import { PLATFORM_TYPES } from '@adobe/spacecat-shared-data-access';
 
 import AccessControlUtil from '../support/access-control-util.js';
 
 const MAX_URLS_PER_REQUEST = 100;
 const DEFAULT_LIMIT = 100;
 const MAX_LIMIT = 500;
+const VALID_PLATFORM_TYPES = Object.values(PLATFORM_TYPES);
 
 /**
  * Canonicalizes a URL by removing trailing slashes, converting to lowercase domain, etc.
@@ -281,6 +283,129 @@ function UrlStoreController(ctx, log) {
     }
   };
 
+  /**
+   * List URLs by platform type with pagination and sorting.
+   * GET /sites/{siteId}/url-store/by-platform/{platformType}
+   */
+  const listUrlsByPlatform = async (context) => {
+    const { siteId, platformType } = context.params;
+    const {
+      limit = DEFAULT_LIMIT,
+      cursor,
+      sortBy,
+      sortOrder = 'asc',
+    } = context.data || {};
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    if (!hasText(platformType)) {
+      return badRequest('Platform type required');
+    }
+
+    // Validate platformType
+    if (!VALID_PLATFORM_TYPES.includes(platformType)) {
+      return badRequest(`Invalid platform type. Must be one of: ${VALID_PLATFORM_TYPES.join(', ')}`);
+    }
+
+    // Validate sortBy field
+    const validSortFields = ['rank', 'traffic', 'url', 'createdAt', 'updatedAt'];
+    if (sortBy && !validSortFields.includes(sortBy)) {
+      return badRequest(`Invalid sortBy field. Must be one of: ${validSortFields.join(', ')}`);
+    }
+
+    // Validate sortOrder
+    if (sortOrder && !['asc', 'desc'].includes(sortOrder)) {
+      return badRequest('Invalid sortOrder. Must be "asc" or "desc"');
+    }
+
+    const parsedLimit = Math.min(parseInt(limit, 10) || DEFAULT_LIMIT, MAX_LIMIT);
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can view URLs');
+    }
+
+    try {
+      const result = await AuditUrl.allBySiteIdAndPlatform(siteId, platformType, {
+        limit: parsedLimit,
+        cursor,
+        sortBy,
+        sortOrder,
+      });
+
+      return ok({
+        items: result.items || [],
+        cursor: result.cursor,
+      });
+    } catch (error) {
+      log.error(`Error listing URLs by platform type for site ${siteId}: ${error.message}`);
+      return internalServerError('Failed to list URLs by platform type');
+    }
+  };
+
+  /**
+   * List all offsite platform URLs (excludes primary-site).
+   * GET /sites/{siteId}/url-store/offsite
+   */
+  const listOffsiteUrls = async (context) => {
+    const { siteId } = context.params;
+    const {
+      limit = DEFAULT_LIMIT,
+      cursor,
+      sortBy,
+      sortOrder = 'asc',
+    } = context.data || {};
+
+    if (!isValidUUID(siteId)) {
+      return badRequest('Site ID required');
+    }
+
+    // Validate sortBy field
+    const validSortFields = ['rank', 'traffic', 'url', 'createdAt', 'updatedAt'];
+    if (sortBy && !validSortFields.includes(sortBy)) {
+      return badRequest(`Invalid sortBy field. Must be one of: ${validSortFields.join(', ')}`);
+    }
+
+    // Validate sortOrder
+    if (sortOrder && !['asc', 'desc'].includes(sortOrder)) {
+      return badRequest('Invalid sortOrder. Must be "asc" or "desc"');
+    }
+
+    const parsedLimit = Math.min(parseInt(limit, 10) || DEFAULT_LIMIT, MAX_LIMIT);
+
+    const site = await Site.findById(siteId);
+    if (!site) {
+      return notFound('Site not found');
+    }
+
+    if (!await accessControlUtil.hasAccess(site)) {
+      return forbidden('Only users belonging to the organization can view URLs');
+    }
+
+    try {
+      const result = await AuditUrl.allOffsiteUrls(siteId, {
+        limit: parsedLimit,
+        cursor,
+        sortBy,
+        sortOrder,
+      });
+
+      return ok({
+        items: result.items || [],
+        cursor: result.cursor,
+      });
+    } catch (error) {
+      log.error(`Error listing offsite URLs for site ${siteId}: ${error.message}`);
+      return internalServerError('Failed to list offsite URLs');
+    }
+  };
+
   /**
    * Get a specific URL by base64 encoded URL.
    * GET /sites/{siteId}/url-store/{base64Url}
@@ -374,6 +499,16 @@ function UrlStoreController(ctx, log) {
         const rank = urlData.rank !== undefined ? urlData.rank : null;
         const traffic = urlData.traffic !== undefined ? urlData.traffic : null;
 
+        // Extract and validate platformType if provided
+        const platformType = urlData.platformType || PLATFORM_TYPES.PRIMARY_SITE;
+        if (platformType && !VALID_PLATFORM_TYPES.includes(platformType)) {
+          return {
+            success: false,
+            url: urlData.url,
+            reason: `Invalid platformType. Must be one of: ${VALID_PLATFORM_TYPES.join(', ')}`,
+          };
+        }
+
         // Check if URL already exists (idempotent)
         let existingUrl = await AuditUrl.findBySiteIdAndUrl(siteId, canonicalUrl);
 
@@ -384,6 +519,7 @@ function UrlStoreController(ctx, log) {
             existingUrl.setAudits(audits);
             if (rank !== null) existingUrl.setRank(rank);
             if (traffic !== null) existingUrl.setTraffic(traffic);
+            if (platformType) existingUrl.setPlatformType(platformType);
             existingUrl.setUpdatedBy(userId);
             existingUrl = await existingUrl.save();
           }
@@ -398,6 +534,7 @@ function UrlStoreController(ctx, log) {
           audits,
           rank,
           traffic,
+          platformType,
           createdBy: userId,
           updatedBy: userId,
         });
@@ -520,6 +657,18 @@ function UrlStoreController(ctx, log) {
           auditUrl.setTraffic(update.traffic);
         }
 
+        // Update platformType if provided
+        if ('platformType' in update) {
+          if (update.platformType && !VALID_PLATFORM_TYPES.includes(update.platformType)) {
+            return {
+              success: false,
+              url: update.url,
+              reason: `Invalid platformType. Must be one of: ${VALID_PLATFORM_TYPES.join(', ')}`,
+            };
+          }
+          auditUrl.setPlatformType(update.platformType);
+        }
+
         auditUrl.setUpdatedBy(userId);
         auditUrl = await auditUrl.save();
 
@@ -675,6 +824,8 @@ function UrlStoreController(ctx, log) {
     listUrls,
     listUrlsBySource,
     listUrlsByAuditType,
+    listUrlsByPlatform,
+    listOffsiteUrls,
     getUrl,
     addUrls,
     updateUrls,
diff --git a/src/routes/index.js b/src/routes/index.js
index 3ba1ad2cc..7bac09ab6 100644
--- a/src/routes/index.js
+++ b/src/routes/index.js
@@ -246,6 +246,8 @@ export default function getRouteHandlers(
     'GET /sites/:siteId/url-store': urlStoreController.listUrls,
     'GET /sites/:siteId/url-store/by-source/:source': urlStoreController.listUrlsBySource,
     'GET /sites/:siteId/url-store/by-audit/:auditType': urlStoreController.listUrlsByAuditType,
+    'GET /sites/:siteId/url-store/by-platform/:platformType': urlStoreController.listUrlsByPlatform,
+    'GET /sites/:siteId/url-store/offsite': urlStoreController.listOffsiteUrls,
     'GET /sites/:siteId/url-store/:base64Url': urlStoreController.getUrl,
     'POST /sites/:siteId/url-store': urlStoreController.addUrls,
     'PATCH /sites/:siteId/url-store': urlStoreController.updateUrls,
diff --git a/test/controllers/url-store-platform.test.js b/test/controllers/url-store-platform.test.js
new file mode 100644
index 000000000..8ea67ec23
--- /dev/null
+++ b/test/controllers/url-store-platform.test.js
@@ -0,0 +1,415 @@
+/*
+ * 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-env mocha */
+
+import { use, expect } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+import sinonChai from 'sinon-chai';
+import sinon from 'sinon';
+import { PLATFORM_TYPES } from '@adobe/spacecat-shared-data-access';
+import UrlStoreController from '../../src/controllers/url-store.js';
+
+use(chaiAsPromised);
+use(sinonChai);
+
+describe('URL Store Controller - Platform Type Support', () => {
+  const sandbox = sinon.createSandbox();
+
+  const mockLogger = {
+    info: sandbox.stub(),
+    error: sandbox.stub(),
+    warn: sandbox.stub(),
+    debug: sandbox.stub(),
+  };
+
+  const mockDataAccess = {
+    AuditUrl: {
+      allBySiteIdAndPlatform: sandbox.stub(),
+      allOffsiteUrls: sandbox.stub(),
+      findBySiteIdAndUrl: sandbox.stub(),
+      create: sandbox.stub(),
+    },
+  };
+
+  let controller;
+
+  beforeEach(() => {
+    controller = UrlStoreController({ dataAccess: mockDataAccess, log: mockLogger });
+  });
+
+  afterEach(() => {
+    sandbox.reset();
+  });
+
+  describe('listUrlsByPlatform', () => {
+    it('returns URLs for a specific platform type', async () => {
+      const mockUrl1 = {
+        getUrl: () => 'https://www.youtube.com/@example',
+        getPlatformType: () => 'youtube-channel',
+        getTraffic: () => 1000000,
+        toJSON: () => ({
+          url: 'https://www.youtube.com/@example',
+          platformType: 'youtube-channel',
+          traffic: 1000000,
+        }),
+      };
+
+      const mockUrl2 = {
+        getUrl: () => 'https://www.youtube.com/@example2',
+        getPlatformType: () => 'youtube-channel',
+        getTraffic: () => 500000,
+        toJSON: () => ({
+          url: 'https://www.youtube.com/@example2',
+          platformType: 'youtube-channel',
+          traffic: 500000,
+        }),
+      };
+
+      mockDataAccess.AuditUrl.allBySiteIdAndPlatform.resolves({
+        items: [mockUrl1, mockUrl2],
+      });
+
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store/by-platform/youtube-channel',
+        },
+        params: {
+          siteId: 'site123',
+          platformType: 'youtube-channel',
+        },
+        data: {},
+      };
+
+      const response = await controller.listUrlsByPlatform(context);
+
+      expect(response.status).to.equal(200);
+      expect(response.body).to.be.an('object');
+      expect(response.body.items).to.be.an('array').with.lengthOf(2);
+      expect(response.body.items[0].platformType).to.equal('youtube-channel');
+      expect(mockDataAccess.AuditUrl.allBySiteIdAndPlatform).to.have.been.calledOnceWith(
+        'site123',
+        'youtube-channel',
+        {},
+      );
+    });
+
+    it('supports sorting by traffic', async () => {
+      mockDataAccess.AuditUrl.allBySiteIdAndPlatform.resolves({ items: [] });
+
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store/by-platform/youtube-channel',
+        },
+        params: {
+          siteId: 'site123',
+          platformType: 'youtube-channel',
+        },
+        data: {
+          sortBy: 'traffic',
+          sortOrder: 'desc',
+        },
+      };
+
+      await controller.listUrlsByPlatform(context);
+
+      expect(mockDataAccess.AuditUrl.allBySiteIdAndPlatform).to.have.been.calledOnceWith(
+        'site123',
+        'youtube-channel',
+        { sortBy: 'traffic', sortOrder: 'desc' },
+      );
+    });
+
+    it('supports pagination', async () => {
+      mockDataAccess.AuditUrl.allBySiteIdAndPlatform.resolves({
+        items: [],
+        cursor: 'next-page-cursor',
+      });
+
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store/by-platform/wikipedia',
+        },
+        params: {
+          siteId: 'site123',
+          platformType: 'wikipedia',
+        },
+        data: {
+          limit: 10,
+          cursor: 'page-cursor',
+        },
+      };
+
+      const response = await controller.listUrlsByPlatform(context);
+
+      expect(response.status).to.equal(200);
+      expect(response.body.cursor).to.equal('next-page-cursor');
+      expect(mockDataAccess.AuditUrl.allBySiteIdAndPlatform).to.have.been.calledOnceWith(
+        'site123',
+        'wikipedia',
+        { limit: 10, cursor: 'page-cursor' },
+      );
+    });
+
+    it('returns 400 for invalid platform type', async () => {
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store/by-platform/invalid-platform',
+        },
+        params: {
+          siteId: 'site123',
+          platformType: 'invalid-platform',
+        },
+        data: {},
+      };
+
+      const response = await controller.listUrlsByPlatform(context);
+
+      expect(response.status).to.equal(400);
+      expect(response.body.message).to.include('Invalid platformType');
+      expect(mockDataAccess.AuditUrl.allBySiteIdAndPlatform).to.not.have.been.called;
+    });
+  });
+
+  describe('listOffsiteUrls', () => {
+    it('returns all offsite platform URLs', async () => {
+      const mockWikiUrl = {
+        getUrl: () => 'https://en.wikipedia.org/wiki/Example',
+        getPlatformType: () => 'wikipedia',
+        toJSON: () => ({
+          url: 'https://en.wikipedia.org/wiki/Example',
+          platformType: 'wikipedia',
+        }),
+      };
+
+      const mockYoutubeUrl = {
+        getUrl: () => 'https://www.youtube.com/@example',
+        getPlatformType: () => 'youtube-channel',
+        toJSON: () => ({
+          url: 'https://www.youtube.com/@example',
+          platformType: 'youtube-channel',
+        }),
+      };
+
+      mockDataAccess.AuditUrl.allOffsiteUrls.resolves({
+        items: [mockWikiUrl, mockYoutubeUrl],
+      });
+
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store/offsite',
+        },
+        params: {
+          siteId: 'site123',
+        },
+        data: {},
+      };
+
+      const response = await controller.listOffsiteUrls(context);
+
+      expect(response.status).to.equal(200);
+      expect(response.body).to.be.an('object');
+      expect(response.body.items).to.be.an('array').with.lengthOf(2);
+      expect(mockDataAccess.AuditUrl.allOffsiteUrls).to.have.been.calledOnceWith(
+        'site123',
+        {},
+      );
+    });
+
+    it('supports sorting by rank', async () => {
+      mockDataAccess.AuditUrl.allOffsiteUrls.resolves({ items: [] });
+
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store/offsite',
+        },
+        params: {
+          siteId: 'site123',
+        },
+        data: {
+          sortBy: 'rank',
+          sortOrder: 'asc',
+        },
+      };
+
+      await controller.listOffsiteUrls(context);
+
+      expect(mockDataAccess.AuditUrl.allOffsiteUrls).to.have.been.calledOnceWith(
+        'site123',
+        { sortBy: 'rank', sortOrder: 'asc' },
+      );
+    });
+
+    it('supports pagination', async () => {
+      mockDataAccess.AuditUrl.allOffsiteUrls.resolves({
+        items: [],
+        cursor: 'next-cursor',
+      });
+
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store/offsite',
+        },
+        params: {
+          siteId: 'site123',
+        },
+        data: {
+          limit: 20,
+          cursor: 'current-cursor',
+        },
+      };
+
+      const response = await controller.listOffsiteUrls(context);
+
+      expect(response.status).to.equal(200);
+      expect(response.body.cursor).to.equal('next-cursor');
+      expect(mockDataAccess.AuditUrl.allOffsiteUrls).to.have.been.calledOnceWith(
+        'site123',
+        { limit: 20, cursor: 'current-cursor' },
+      );
+    });
+  });
+
+  describe('addUrls - platformType handling', () => {
+    it('accepts valid platformType in URL payload', async () => {
+      mockDataAccess.AuditUrl.findBySiteIdAndUrl.resolves(null);
+      mockDataAccess.AuditUrl.create.resolves({
+        getUrl: () => 'https://www.youtube.com/@example',
+        getPlatformType: () => 'youtube-channel',
+        toJSON: () => ({
+          url: 'https://www.youtube.com/@example',
+          platformType: 'youtube-channel',
+        }),
+      });
+
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store',
+        },
+        params: {
+          siteId: 'site123',
+        },
+        data: {
+          urls: [
+            {
+              url: 'https://www.youtube.com/@example',
+              platformType: 'youtube-channel',
+              audits: ['broken-backlinks'],
+            },
+          ],
+        },
+        attributes: {
+          authInfo: {
+            getProfile: () => ({ email: 'user@example.com' }),
+          },
+        },
+      };
+
+      const response = await controller.addUrls(context);
+
+      expect(response.status).to.equal(207);
+      expect(mockDataAccess.AuditUrl.create).to.have.been.calledOnce;
+      const createCall = mockDataAccess.AuditUrl.create.getCall(0);
+      expect(createCall.args[0].platformType).to.equal('youtube-channel');
+    });
+
+    it('defaults to primary-site when platformType not provided', async () => {
+      mockDataAccess.AuditUrl.findBySiteIdAndUrl.resolves(null);
+      mockDataAccess.AuditUrl.create.resolves({
+        getUrl: () => 'https://example.com/page',
+        getPlatformType: () => 'primary-site',
+        toJSON: () => ({
+          url: 'https://example.com/page',
+          platformType: 'primary-site',
+        }),
+      });
+
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store',
+        },
+        params: {
+          siteId: 'site123',
+        },
+        data: {
+          urls: [
+            {
+              url: 'https://example.com/page',
+              audits: ['broken-backlinks'],
+            },
+          ],
+        },
+        attributes: {
+          authInfo: {
+            getProfile: () => ({ email: 'user@example.com' }),
+          },
+        },
+      };
+
+      const response = await controller.addUrls(context);
+
+      expect(response.status).to.equal(207);
+      expect(mockDataAccess.AuditUrl.create).to.have.been.calledOnce;
+      const createCall = mockDataAccess.AuditUrl.create.getCall(0);
+      expect(createCall.args[0].platformType).to.equal('primary-site');
+    });
+
+    it('rejects invalid platformType', async () => {
+      const context = {
+        pathInfo: {
+          suffix: '/sites/site123/url-store',
+        },
+        params: {
+          siteId: 'site123',
+        },
+        data: {
+          urls: [
+            {
+              url: 'https://example.com/page',
+              platformType: 'invalid-platform-type',
+              audits: [],
+            },
+          ],
+        },
+        attributes: {
+          authInfo: {
+            getProfile: () => ({ email: 'user@example.com' }),
+          },
+        },
+      };
+
+      const response = await controller.addUrls(context);
+
+      expect(response.status).to.equal(207);
+      expect(response.body.results[0].success).to.be.false;
+      expect(response.body.results[0].reason).to.include('Invalid platformType');
+      expect(mockDataAccess.AuditUrl.create).to.not.have.been.called;
+    });
+  });
+
+  describe('PLATFORM_TYPES constant', () => {
+    it('is exported from data access layer', () => {
+      expect(PLATFORM_TYPES).to.be.an('object');
+      expect(PLATFORM_TYPES.PRIMARY_SITE).to.equal('primary-site');
+      expect(PLATFORM_TYPES.WIKIPEDIA).to.equal('wikipedia');
+      expect(PLATFORM_TYPES.YOUTUBE_CHANNEL).to.equal('youtube-channel');
+      expect(PLATFORM_TYPES.REDDIT_COMMUNITY).to.equal('reddit-community');
+      expect(PLATFORM_TYPES.FACEBOOK_PAGE).to.equal('facebook-page');
+      expect(PLATFORM_TYPES.TWITTER_PROFILE).to.equal('twitter-profile');
+      expect(PLATFORM_TYPES.LINKEDIN_COMPANY).to.equal('linkedin-company');
+      expect(PLATFORM_TYPES.INSTAGRAM_ACCOUNT).to.equal('instagram-account');
+      expect(PLATFORM_TYPES.TIKTOK_ACCOUNT).to.equal('tiktok-account');
+      expect(PLATFORM_TYPES.GITHUB_ORG).to.equal('github-org');
+      expect(PLATFORM_TYPES.MEDIUM_PUBLICATION).to.equal('medium-publication');
+    });
+  });
+});