chore: validate specs on ci/cli

Author: shortcuts

scripts/common.ts

@@ -73,7 +73,7 @@ export const LANGUAGES = [...new Set(Object.values(GENERATORS).map((gen) => gen.
 
 // `crawler` is manually added so we can still bundled and validate the specs
 // the entry can be removed once at least one client is generated
-export const CLIENTS = [...new Set(Object.values(GENERATORS).map((gen) => gen.client)), 'crawler'];
+export const CLIENTS = [...new Set(Object.values(GENERATORS).map((gen) => gen.client)), 'crawler', 'abtesting-v3'];
 
 export async function run(command: string, { errorMessage, cwd, language }: RunOptions = {}): Promise<string> {
   const realCwd = path.resolve(ROOT_DIR, cwd ?? '.');

specs/abtesting-v3/common/parameters.yml

@@ -5,13 +5,13 @@ ID:
   description: Unique A/B test identifier.
   required: true
   schema:
-    $ref: "#/abTestID"
+    $ref: '#/abTestID'
 
 # misc
 index:
   type: string
   description: Index name of the A/B test variant (case-sensitive).
-  example: "delcourt_production"
+  example: 'delcourt_production'
 
 abTestID:
   type: integer
@@ -75,7 +75,7 @@ currencies:
       mean: 43.7
       standardDeviation: 10.3
   additionalProperties:
-    $ref: "#/currency"
+    $ref: '#/currency'
     x-additionalPropertiesName: currency code
 
 currency:
@@ -84,7 +84,7 @@ currency:
     currency:
       type: string
       description: Currency code.
-      example: "USD"
+      example: 'USD'
     revenue:
       type: number
       format: double

specs/abtesting-v3/common/schemas/ABTest.yml

@@ -3,31 +3,39 @@ ABTests:
     - type: array
       description: A/B tests.
       items:
-        $ref: "#/ABTest"
-    - type: "null"
+        $ref: '#/ABTest'
+    - type: 'null'
+
+EmptySearch:
+  type: object
+  description: Configuration for handling empty searches.
+  properties:
+    exclude:
+      type: boolean
+      description: Whether to exclude empty searches when calculating A/B test results.
 
 ABTest:
   type: object
   additionalProperties: false
   properties:
     abTestID:
-      $ref: "../parameters.yml#/abTestID"
+      $ref: '../parameters.yml#/abTestID'
     updatedAt:
-      $ref: "../parameters.yml#/updatedAt"
+      $ref: '../parameters.yml#/updatedAt'
     createdAt:
-      $ref: "../parameters.yml#/createdAt"
+      $ref: '../parameters.yml#/createdAt'
     endAt:
-      $ref: "../parameters.yml#/endAt"
+      $ref: '../parameters.yml#/endAt'
     name:
-      $ref: "../parameters.yml#/name"
+      $ref: '../parameters.yml#/name'
     status:
-      $ref: "#/Status"
+      $ref: '#/Status'
     variants:
-      $ref: "Variant.yml#/variants"
+      $ref: 'Variant.yml#/variants'
     configuration:
-      $ref: "#/ABTestConfiguration"
+      $ref: '#/ABTestConfiguration'
     migratedAbTestID:
-      $ref: "#/MigratedABTestId"
+      $ref: '#/MigratedABTestId'
   required:
     - status
     - name
@@ -59,11 +67,11 @@ ABTestConfiguration:
   description: A/B test configuration.
   properties:
     minimumDetectableEffect:
-      $ref: "#/MinimumDetectableEffect"
+      $ref: '#/MinimumDetectableEffect'
     filters:
-      $ref: "#/MetricsFilters"
+      $ref: '#/MetricsFilters'
     errorCorrection:
-      $ref: "#/ErrorCorrectionType"
+      $ref: '#/ErrorCorrectionType'
 
 MinimumDetectableEffect:
   type: object
@@ -78,7 +86,7 @@ MinimumDetectableEffect:
         Smallest difference in an observable metric between variants.
         For example, to detect a 10% difference between variants, set this value to 0.1.
     metric:
-      $ref: "#/EffectMetric"
+      $ref: '#/EffectMetric'
   required:
     - size
     - metric
@@ -127,7 +135,7 @@ MetricsFilters:
   type: array
   description: List of metric filters applied to the test population.
   items:
-    $ref: "#/MetricsFilter"
+    $ref: '#/MetricsFilter'
 
 ErrorCorrectionType:
   type: string

specs/abtesting-v3/common/schemas/Timeseries.yml

@@ -3,9 +3,9 @@ Timeseries:
   additionalProperties: false
   properties:
     abTestID:
-      $ref: "../parameters.yml#/abTestID"
+      $ref: '../parameters.yml#/abTestID'
     variants:
-      $ref: "#/timeseriesVariants"
+      $ref: '#/timeseriesVariants'
   required:
     - abTestID
     - variants
@@ -18,18 +18,18 @@ timeseriesVariants:
     The first variant is your _control_ index, typically your production index.
     All of the additional variants are indexes with changed settings that you want to test against the control.
   items:
-    $ref: "#/timeseriesVariant"
+    $ref: '#/timeseriesVariant'
 
 timeseriesVariant:
   type: object
   properties:
     dates:
-      $ref: "#/metricDates"
+      $ref: '#/metricDates'
 
 metricDates:
   type: array
   items:
-    $ref: "#/metricDate"
+    $ref: '#/metricDate'
 
 metricDate:
   type: object
@@ -40,4 +40,23 @@ metricDate:
       format: date
       example: 2025-06-15
     metrics:
-       $ref: "Variant.yml#/metrics"
+      $ref: 'Variant.yml#/metrics'
+
+Metric:
+  type: string
+  enum:
+    - search_count
+    - tracked_search_count
+    - user_count
+    - tracked_user_count
+    - no_result_count
+    - add_to_cart_count
+    - purchase_count
+    - clicked_search_count
+    - converted_search_count
+    - click_through_rate
+    - conversion_rate
+    - add_to_cart_rate
+    - purchase_rate
+    - average_click_position
+    - revenue

specs/abtesting-v3/paths/abtests.yml

@@ -16,49 +16,49 @@ post:
           additionalProperties: false
           properties:
             name:
-              $ref: "../common/parameters.yml#/name"
+              $ref: '../common/parameters.yml#/name'
             variants:
               type: array
               description: A/B test variants.
               minItems: 2
               items:
-                $ref: "../common/schemas/AddABTestsVariant.yml#/AddABTestsVariant"
+                $ref: '../common/schemas/AddABTestsVariant.yml#/AddABTestsVariant'
             metrics:
               type: array
               description: A/B test metrics involved in the test. Only these metrics will be considered when calculating results. 
               items:
-                $ref: "../common/parameters.yml#/metric"
+                $ref: '../common/parameters.yml#/metric'
             configuration:
-              $ref: "../common/schemas/ABTest.yml#/ABTestConfiguration"
+              $ref: '../common/schemas/ABTest.yml#/ABTestConfiguration'
             endAt:
-              $ref: "../common/parameters.yml#/endAt"
+              $ref: '../common/parameters.yml#/endAt'
           required:
             - name
             - variants
             - metrics
             - endAt
   responses:
-    "200":
+    '200':
       description: OK
       headers:
         x-ratelimit-limit:
-          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-limit"
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
         x-ratelimit-remaining:
-          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-remaining"
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
         x-ratelimit-reset:
-          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-reset"
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
       content:
         application/json:
           schema:
-            $ref: "../common/schemas/ABTestResponse.yml#/ABTestResponse"
-    "400":
-      $ref: "../../common/responses/BadRequest.yml"
-    "402":
-      $ref: "../../common/responses/FeatureNotEnabled.yml"
-    "403":
-      $ref: "../../common/responses/MethodNotAllowed.yml"
-    "404":
-      $ref: "../../common/responses/IndexNotFound.yml"
+            $ref: '../common/schemas/ABTestResponse.yml#/ABTestResponse'
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'
 
 get:
   tags:
@@ -87,25 +87,25 @@ get:
     - name: indexPrefix
       in: query
       description: Index name prefix. Only A/B tests for indices starting with this string are included in the response.
-      example: "dev_"
+      example: 'dev_'
       schema:
         type: string
     - name: indexSuffix
       in: query
       description: Index name suffix. Only A/B tests for indices ending with this string are included in the response.
-      example: "_development"
+      example: '_development'
       schema:
         type: string
   responses:
-    "200":
+    '200':
       description: OK
       headers:
         x-ratelimit-limit:
-          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-limit"
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-limit'
         x-ratelimit-remaining:
-          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-remaining"
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-remaining'
         x-ratelimit-reset:
-          $ref: "../../common/responses/rateLimit.yml#/x-ratelimit-reset"
+          $ref: '../../common/responses/rateLimit.yml#/x-ratelimit-reset'
       content:
         application/json:
           schema:
@@ -114,7 +114,7 @@ get:
             additionalProperties: false
             properties:
               abtests:
-                $ref: "../common/schemas/ABTest.yml#/ABTests"
+                $ref: '../common/schemas/ABTest.yml#/ABTests'
               count:
                 type: integer
                 description: Number of A/B tests.
@@ -127,11 +127,11 @@ get:
               - abtests
               - count
               - total
-    "400":
-      $ref: "../../common/responses/BadRequest.yml"
-    "402":
-      $ref: "../../common/responses/FeatureNotEnabled.yml"
-    "403":
-      $ref: "../../common/responses/MethodNotAllowed.yml"
-    "404":
-      $ref: "../../common/responses/IndexNotFound.yml"
+    '400':
+      $ref: '../../common/responses/BadRequest.yml'
+    '402':
+      $ref: '../../common/responses/FeatureNotEnabled.yml'
+    '403':
+      $ref: '../../common/responses/MethodNotAllowed.yml'
+    '404':
+      $ref: '../../common/responses/IndexNotFound.yml'

specs/abtesting-v3/paths/timeseries.yml

@@ -16,24 +16,7 @@ get:
       schema:
         type: array
         items:
-          type: string
-          enum:
-            - search_count
-            - tracked_search_count
-            - user_count
-            - tracked_user_count
-            - no_result_count
-            - add_to_cart_count
-            - purchase_count
-            - clicked_search_count
-            - converted_search_count
-            - click_through_rate
-            - conversion_rate
-            - add_to_cart_rate
-            - purchase_rate
-            - average_click_position
-            - revenue
-        example: ["search_count", "click_through_rate", "conversion_rate"]
+          $ref: '../common/schemas/Timeseries.yml#/Metric'
   responses:
     '200':
       description: OK

specs/abtesting-v3/spec.yml

@@ -58,9 +58,9 @@ info:
 components:
   securitySchemes:
     appId:
-      $ref: "../common/securitySchemes.yml#/appId"
+      $ref: '../common/securitySchemes.yml#/appId'
     apiKey:
-      $ref: "../common/securitySchemes.yml#/apiKey"
+      $ref: '../common/securitySchemes.yml#/apiKey'
 servers:
   - url: https://analytics.{region}.algolia.com
     variables:
@@ -89,23 +89,23 @@ paths:
   # ### Custom request ###
   # ######################
   /{path}:
-    $ref: "../common/paths/customRequest.yml"
+    $ref: '../common/paths/customRequest.yml'
 
   /3/abtests:
-    $ref: "paths/abtests.yml"
+    $ref: 'paths/abtests.yml'
   /3/abtests/{id}:
-    $ref: "paths/abtest.yml"
+    $ref: 'paths/abtest.yml'
   /3/abtests/{id}/stop:
-    $ref: "paths/stopABTest.yml"
+    $ref: 'paths/stopABTest.yml'
   /3/abtests/schedule:
-    $ref: "paths/scheduleABTest.yml"
+    $ref: 'paths/scheduleABTest.yml'
   /3/abtests/estimate:
-    $ref: "paths/estimate.yml"
+    $ref: 'paths/estimate.yml'
   /3/abtests/{id}/timeseries:
-    $ref: "paths/timeseries.yml"
+    $ref: 'paths/timeseries.yml'
 
   # ###############
   # ### Helpers ###
   # ###############
   /setClientApiKey:
-    $ref: "../common/helpers/setClientApiKey.yml#/method"
+    $ref: '../common/helpers/setClientApiKey.yml#/method'