feat(api-spec): analytics site integration API spec (#188)

Implements: SITES-20862

After the setup for an analytics solution is completed for the site represented by the base URL, the new hook will be called with the different artifacts details. SpaceCat will use these in its automations such as:
- notifying users about the new reporting available
- opening a PR to embed the data collection scripts into the site
- importing RUM data into the analytics solution (Adobe Analytics or Customer Journey Analytics)

The SpaceCat site id will be used as a shared identifier between SpaceCat and Omnivore, as it's more stable than the baseURL.
SpaceCat will initially start using siteId, dataCollection and reporting, as required by the Slack-based flow.
Implementation will be done via #237

docs/openapi/api.yaml

@@ -55,6 +55,8 @@ paths:
     $ref: './hooks-api.yaml#/site-detection-cdn'
   /hooks/site-detection/rum/{hookSecret}:
     $ref: './hooks-api.yaml#/site-detection-rum'
+  /hooks/site-integration/analytics/{hookSecret}:
+    $ref: './hooks-api.yaml#/site-integration-analytics'
   /organizations:
     $ref: './organizations-api.yaml#/organizations'
   /organizations/{organizationId}:
@@ -102,3 +104,5 @@ components:
       name: x-api-key
   schemas:
     $ref: './schemas.yaml'
+  examples:
+    $ref: './examples.yaml'

docs/openapi/examples.yaml

@@ -0,0 +1,92 @@
+analytics-site-integration-aa-tags:
+  summary: Example for an integration with Adobe Analytics via Adobe Tags
+  value:
+    siteId: 'a31fa5e4-90be-4440-a063-e6d6aa5a127a'
+    reporting:
+      link: 'https://www5.an.adobe.com/x/5_19xzaq4'
+      timezone: 'UTC-07:00'
+    dataCollection:
+      type: 'adobe-tags'
+      environments:
+        development: 'https://assets.adobedtm.com/51b39232f777/342ccd9ca453/launch-e2732f4a5678-development.min.js'
+        production: 'https://assets.adobedtm.com/51b39232f777/342ccd9ca453/launch-e2732f4a5678.min.js'
+    dataStore:
+      type: 'adobe-analytics'
+      id: 'ageo1xxpnwexamplerumanalytics'
+    dataMapping:
+      type: 'adobe-analytics'
+      mappings:
+        'All Page Views': 'event4'
+        'Page URL': 'evar2'
+        'Data Source': 'evar3'
+        'Site Domain': 'evar4'
+analytics-site-integration-aa-aep-websdk:
+  summary: Example for an integration with Adobe Analytics via Adobe Experience Platform and WebSDK
+  value:
+    siteId: 'a31fa5e4-90be-4440-a063-e6d6aa5a127a'
+    reporting:
+      link: 'https://www5.an.adobe.com/x/5_19xzaq4'
+      timezone: 'UTC-07:00'
+    dataCollection:
+      type: 'aep-websdk'
+      environments:
+        development: 'caad777c-c410-4ceb-8b36-167f12435'
+        production: 'caad777c-c410-4ceb-43f2-167f12435'
+    dataStore:
+      type: 'adobe-analytics'
+      id: 'ageo1xxpnwexamplerumanalytics'
+    dataMapping:
+      type: 'xdm'
+      mappings:
+        'All Page Views': 'web.webPageDetails.pageViews.value'
+        'Page URL': 'web.webPageDetails.URL'
+        'Data Source': '_example.dataSource'
+        'Site Domain': 'web.webPageDetails.server'
+analytics-site-integration-cja-tags:
+  summary: Example for an integration with Customer Adobe Analytics via Adobe Experience Platform and Adobe Tags
+  value:
+    siteId: 'a31fa5e4-90be-4440-a063-e6d6aa5a127a'
+    reporting:
+      link: 'https://analytics.adobe.com/?linkId=8296eaea-aa9a-4840-8a86-71df75661&dpc=acc'
+      timezone: 'UTC-07:00'
+    dataCollection:
+      type: 'adobe-tags'
+      environments:
+        development: 'https://assets.adobedtm.com/51b39232f777/342ccd9ca453/launch-e2732f4a5678-development.min.js'
+        production: 'https://assets.adobedtm.com/51b39232f777/342ccd9ca453/launch-e2732f4a5678.min.js'
+    dataStore:
+      type: 'aep'
+      id: '64cd250cdc886828d309a2215'
+    dataSchema:
+      id: 'https://ns.adobe.com/example/schemas/203ff63ed073c85d5fad4274f27d2fc2e9b834b06778f8'
+    dataMapping:
+      type: 'xdm'
+      mappings:
+        'All Page Views': 'web.webPageDetails.pageViews.value'
+        'Page URL': 'web.webPageDetails.URL'
+        'Data Source': '_example.dataSource'
+        'Site Domain': 'web.webPageDetails.server'
+analytics-site-integration-cja-websdk:
+  summary: Example for an integration with Customer Adobe Analytics via Adobe Experience Platform and WebSDK
+  value:
+    siteId: 'a31fa5e4-90be-4440-a063-e6d6aa5a127a'
+    reporting:
+      link: 'https://analytics.adobe.com/?linkId=8296eaea-aa9a-4840-8a86-71df75661&dpc=acc'
+      timezone: 'UTC-07:00'
+    dataCollection:
+      type: 'aep-websdk'
+      environments:
+        development: 'caad777c-c410-4ceb-8b36-167f12435'
+        production: 'caad777c-c410-4ceb-43f2-167f12435'
+    dataStore:
+      type: 'aep'
+      id: '64cd250cdc886828d309a2215'
+    dataSchema:
+      id: 'https://ns.adobe.com/example/schemas/203ff63ed073c85d5fad4274f27d2fc2e9b834b06778f8'
+    dataMapping:
+      type: 'xdm'
+      mappings:
+        'All Page Views': 'web.webPageDetails.pageViews.value'
+        'Page URL': 'web.webPageDetails.URL'
+        'Data Source': '_example.dataSource'
+        'Site Domain': 'web.webPageDetails.server'

docs/openapi/hooks-api.yaml

@@ -58,4 +58,43 @@ site-detection-rum:
         $ref: './responses.yaml#/500'
     security:
       - api_key: [ ]
+site-integration-analytics:
+  parameters:
+    - $ref: './parameters.yaml#/hookSecret'
+  post:
+    tags:
+      - hooks
+    summary: Process setup completed events for site integration with analytics
+    description: |
+      Not implemented yet (will be via https://github.com/adobe/spacecat-api-service/issues/237).
+      Process setup completed events for site integration with analytics.
+    operationId: processAnalyticsSiteIntegration
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: './schemas.yaml#/AnalyticsSiteIntegration'
+          examples:
+            analytics-site-integration-aa-tags:
+              $ref: './examples.yaml#/analytics-site-integration-aa-tags'
+            analytics-site-integration-aa-aep-websdk:
+              $ref: './examples.yaml#/analytics-site-integration-aa-aep-websdk'
+            analytics-site-integration-cja-tags:
+              $ref: './examples.yaml#/analytics-site-integration-cja-tags'
+            analytics-site-integration-cja-websdk:
+              $ref: './examples.yaml#/analytics-site-integration-cja-websdk'
+    responses:
+      '202':
+        description: Accepted for processing
+      '400':
+        $ref: './responses.yaml#/400-no-site-id'
+      '401':
+        $ref: './responses.yaml#/401'
+      '404':
+        $ref: './responses.yaml#/404-site-not-found-with-id'
+      '500':
+        $ref: './responses.yaml#/500'
+    security:
+      - api_key: [ ]
 

docs/openapi/schemas.yaml

@@ -696,3 +696,119 @@ Job:
     type:
       type: string
       description: The job type, indicating the specific action or task that the job performs, such as 'rum-to-aa' indicating a data import job from RUM to AA.
+AnalyticsSiteIntegration:
+  type: object
+  additionalProperties: true
+  required:
+    - siteId
+    - reporting
+    - dataCollection
+    - dataStore
+    - dataMapping
+  properties:
+    siteId:
+      description: The site ID in uuid format
+      $ref: '#/Id'
+    reporting:
+      description: The reporting details
+      type: object
+      required:
+        - link
+      additionalProperties: true
+      properties:
+        link:
+          description: |
+            The link to the report in the reporting tool.
+            For Adobe Analytics and Customer Journey Analytics, the link to the Analysis Workspace report.
+          $ref: '#/URL'
+        timezone:
+          description: The timezone for the data in the report
+          type: string
+    dataCollection:
+      description: The configuration for the data collection to embed on the site.
+      type: object
+      required:
+        - type
+        - environments
+      properties:
+        type:
+          description: The type of the data collection
+          type: string
+          enum:
+            - 'adobe-tags'
+            - 'aep-websdk'
+        environments:
+          description: |
+            The environments for the data collection script.
+            At least the script for the production environment is required.
+            The keys represent the environments (development, staging, production).
+            The values represent the URL or ID of the data collection script.
+            For Adobe Analytics and Customer Journey Analytics, the values are either
+            URL for the Adobe Launch script or the datastream ID.
+          type: object
+          additionalProperties:
+            type: string
+          required:
+            - production
+          properties:
+            production:
+              description: The URL or ID of the production data collection script
+              type: string
+    dataStore:
+      description: The data store details
+      type: object
+      required:
+        - id
+        - type
+      additionalProperties: true
+      properties:
+        id:
+          description: The ID of the data store
+          type: string
+        type:
+          description: The type of the data store
+          type: string
+          enum:
+            - 'adobe-analytics'
+            - 'aep'
+    dataSchema:
+      description: The data schema details
+      type: object
+      required:
+        - id
+      additionalProperties: true
+      properties:
+        id:
+          description: The ID of the data schema
+          type: string
+    dataMapping:
+      description: The data mapping details
+      type: object
+      required:
+        - type
+        - mappings
+      properties:
+        type:
+          description: The type of the data mapping
+          type: string
+          enum:
+            - 'adobe-analytics'
+            - 'xdm'
+        mappings:
+          description: |
+            The data mapping details. The keys represent human-friendly naming of metrics and dimensions captured by the
+            instrumentation of the site. The values represent the corresponding metric and dimension names in the data store.
+            For Adobe Analytics, the values are either evars or events.
+            For XDM, the values are the paths in the data schema.
+          type: object
+          additionalProperties:
+            type: string
+  examples:
+    analytics-site-integration-aa-tags:
+      $ref: './examples.yaml#/analytics-site-integration-aa-tags'
+    analytics-site-integration-aa-aep-websdk:
+      $ref: './examples.yaml#/analytics-site-integration-aa-aep-websdk'
+    analytics-site-integration-cja-tags:
+      $ref: './examples.yaml#/analytics-site-integration-cja-tags'
+    analytics-site-integration-cja-websdk:
+      $ref: './examples.yaml#/analytics-site-integration-cja-websdk'