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.

Author: HollywoodTonight

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:

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:

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'