@coveo/thermidor-schema 1.0.0-beta.1 → 1.0.0-beta.13

package/schema/components/cart.schema.json

@@ -2,32 +2,32 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/cart.schema.json",
   "title": "Cart",
-  "description": "Renders the current cart contents and exposes actions for the frontend to manage line items.",
+  "description": "Represents a commerce cart or checkout surface. The backend owns cart state; semantic cart mutations and purchase completion are dispatched through this component.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "cart"
+      "const": "Cart"
+    },
+    "id": {
+      "type": "string"
     },
     "state": {
       "$ref": "#/$defs/CartState"
     },
     "actions": {
       "type": "object",
-      "required": [
-        "setItems",
-        "updateItemQuantity"
-      ],
+      "required": ["updateCart", "purchase"],
       "properties": {
-        "setItems": {
-          "$ref": "#/$defs/SetItemsAction"
+        "updateCart": {
+          "$ref": "#/$defs/UpdateCartAction"
         },
-        "updateItemQuantity": {
-          "$ref": "#/$defs/UpdateItemQuantityAction"
+        "purchase": {
+          "$ref": "#/$defs/PurchaseAction"
         }
       },
       "additionalProperties": false
@@ -37,26 +37,14 @@
   "$defs": {
     "CartState": {
       "title": "CartState",
-      "description": "The current contents of the cart. Owned exclusively by the backend; the frontend must not mutate this directly.",
-      "$comment": "This schema validates the runtime state value the backend pushes to the frontend.",
+      "description": "Cart state is backend-owned. This initial contract intentionally carries no presentation fields; it provides the canonical action anchor for cart mutations and checkout completion.",
       "type": "object",
-      "required": [
-        "items"
-      ],
-      "properties": {
-        "items": {
-          "type": "array",
-          "description": "The current line items in the cart.",
-          "items": {
-            "$ref": "https://schema.thermidor.coveo.com/definitions/cart-item.schema.json"
-          }
-        }
-      },
+      "properties": {},
       "additionalProperties": false
     },
-    "SetItemsAction": {
-      "title": "setItems",
-      "description": "Replaces the entire cart contents with the provided list of items.",
+    "UpdateCartAction": {
+      "title": "updateCart",
+      "description": "Applies a semantic item update to the cart and records the corresponding commerce cart event.",
       "allOf": [
         {
           "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
@@ -65,25 +53,35 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "items"
-          ],
+          "required": ["productId", "quantity", "operation"],
           "properties": {
-            "items": {
-              "type": "array",
-              "description": "The new complete list of cart items. An empty array clears the cart.",
-              "items": {
-                "$ref": "https://schema.thermidor.coveo.com/definitions/cart-item.schema.json"
-              }
+            "productId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "name": {
+              "type": "string"
+            },
+            "price": {
+              "type": ["number", "null"]
+            },
+            "quantity": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "operation": {
+              "title": "CartUpdateOperation",
+              "type": "string",
+              "enum": ["add", "remove", "setQuantity"]
             }
           },
           "additionalProperties": false
         }
       }
     },
-    "UpdateItemQuantityAction": {
-      "title": "updateItemQuantity",
-      "description": "Updates the quantity of a single existing cart line item identified by productId.",
+    "PurchaseAction": {
+      "title": "purchase",
+      "description": "Records a completed commerce transaction.",
       "allOf": [
         {
           "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
@@ -92,17 +90,58 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "item"
-          ],
+          "required": ["products", "transaction"],
           "properties": {
-            "item": {
-              "$ref": "https://schema.thermidor.coveo.com/definitions/cart-item.schema.json"
+            "products": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/PurchaseProduct"
+              }
+            },
+            "transaction": {
+              "$ref": "#/$defs/Transaction"
             }
           },
           "additionalProperties": false
         }
       }
+    },
+    "PurchaseProduct": {
+      "title": "PurchaseProduct",
+      "type": "object",
+      "required": ["productId", "quantity"],
+      "properties": {
+        "productId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "price": {
+          "type": ["number", "null"]
+        },
+        "quantity": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "Transaction": {
+      "title": "Transaction",
+      "type": "object",
+      "required": ["id", "revenue"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "revenue": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
     }
   }
-}
+}

package/schema/components/category-facet.schema.json

@@ -9,9 +9,36 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "category-facet"
+      "const": "CategoryFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The index field the facet operates on, bound to /state/<id>/field."
+    },
+    "displayName": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The facet's human-readable label, bound to /state/<id>/displayName."
+    },
+    "values": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The category facet values, bound to /state/<id>/values."
+    },
+    "canShowMoreValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether more facet values can be shown, bound to /state/<id>/canShowMoreValues."
+    },
+    "canShowLessValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether fewer facet values can be shown, bound to /state/<id>/canShowLessValues."
+    },
+    "facetSearch": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The facet search state, bound to /state/<id>/facetSearch."
     },
     "state": {
       "$ref": "#/$defs/CategoryFacetState"
@@ -99,11 +126,7 @@
       "title": "CategoryFacetValues",
       "description": "Flat representation of the category hierarchy. When no category is selected, ancestry and selected are null and children contains the top-level categories.",
       "type": "object",
-      "required": [
-        "ancestry",
-        "selected",
-        "children"
-      ],
+      "required": ["ancestry", "selected", "children"],
       "properties": {
         "ancestry": {
           "type": "array",
@@ -137,11 +160,7 @@
       "title": "CategoryFacetSearch",
       "description": "The current category facet search state.",
       "type": "object",
-      "required": [
-        "query",
-        "canShowMoreResults",
-        "results"
-      ],
+      "required": ["query", "canShowMoreResults", "results"],
       "properties": {
         "query": {
           "type": "string",
@@ -173,9 +192,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "path"
-          ],
+          "required": ["path"],
           "properties": {
             "path": {
               "type": "array",
@@ -209,9 +226,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "query"
-          ],
+          "required": ["query"],
           "properties": {
             "query": {
               "type": "string",
@@ -263,11 +278,7 @@
       "title": "CategoryFacetValue",
       "description": "A single category value. Used throughout the category facet state (ancestry, selected value, children) and as facet search results.",
       "type": "object",
-      "required": [
-        "path",
-        "value",
-        "numberOfResults"
-      ],
+      "required": ["path", "value", "numberOfResults"],
       "properties": {
         "path": {
           "type": "array",
@@ -289,4 +300,4 @@
       "additionalProperties": false
     }
   }
-}
+}

package/schema/components/commerce-search.schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/commerce-search.schema.json",
+  "title": "CommerceSearch",
+  "description": "Surface-root component for a commerce search surface. Its component discriminant carries the surface intent; it owns the surface's top-level components via named child slots and dispatches search lifecycle actions (submitQuery, restoreState, overrideCorrection).",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "CommerceSearch"
+    },
+    "sidebarChild": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+      "description": "The sidebar named slot: a static ComponentId the renderer mounts by name via children(sidebarChild).",
+      "$comment": "Heterogeneous named-slot composition: CommerceSearch uses named ComponentId slots (sidebar, main) rather than a positional children[] array."
+    },
+    "mainChild": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+      "description": "The main-area named slot: a static ComponentId the renderer mounts by name via children(mainChild)."
+    },
+    "state": {
+      "$ref": "#/$defs/CommerceSearchState"
+    },
+    "actions": {
+      "type": "object",
+      "required": ["submitQuery", "restoreState", "overrideCorrection"],
+      "properties": {
+        "submitQuery": {
+          "$ref": "#/$defs/SubmitQueryAction"
+        },
+        "restoreState": {
+          "$ref": "#/$defs/RestoreStateAction"
+        },
+        "overrideCorrection": {
+          "$ref": "#/$defs/OverrideCorrectionAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "CommerceSearchState": {
+      "title": "CommerceSearchState",
+      "description": "The commerce search surface state. Owned exclusively by the backend.",
+      "type": "object",
+      "additionalProperties": false
+    },
+    "SubmitQueryAction": {
+      "title": "submitQuery",
+      "description": "Submits a new search query.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["query"],
+          "properties": {
+            "query": {
+              "type": "string",
+              "description": "The query string to submit."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "RestoreStateAction": {
+      "title": "restoreState",
+      "description": "Restores a commerce-search surface from externally persisted search state.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["query", "page", "pageSize"],
+          "properties": {
+            "query": {
+              "type": "string"
+            },
+            "page": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "pageSize": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "sortCriteria": {
+              "type": "string"
+            },
+            "facets": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/FacetRestore"
+              }
+            },
+            "pinnedProducts": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "OverrideCorrectionAction": {
+      "title": "overrideCorrection",
+      "description": "Re-runs a search with the shopper's original query instead of an automatic correction.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["originalQuery"],
+          "properties": {
+            "originalQuery": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "FacetRestore": {
+      "title": "FacetRestore",
+      "type": "object",
+      "required": ["facetId"],
+      "properties": {
+        "facetId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "values": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "numericRanges": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/NumericRangeRestore"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "NumericRangeRestore": {
+      "title": "NumericRangeRestore",
+      "type": "object",
+      "required": ["start", "end"],
+      "properties": {
+        "start": {
+          "type": "number"
+        },
+        "end": {
+          "type": "number"
+        },
+        "endInclusive": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/components/comparison-table.schema.json

@@ -2,16 +2,35 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/comparison-table.schema.json",
   "title": "ComparisonTable",
-  "description": "Renders a tabular product comparison with attribute columns. Read-only: the product set and attributes are owned by the backend.",
+  "description": "Renders a tabular product comparison. A leaf component that owns its framing (heading and AI summary), the compared products, and the ordered attribute descriptors defining the comparison rows. Read-only: the product set, attributes, and framing are owned by the backend.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "comparison-table"
+      "const": "ComparisonTable"
+    },
+    "heading": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The table heading, bound to /state/<id>/heading."
+    },
+    "summary": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The AI summary text, bound to /state/<id>/summary."
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The compared products, bound to /state/<id>/products."
+    },
+    "attributes": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The ordered attribute descriptors, bound to /state/<id>/attributes."
     },
     "state": {
       "$ref": "#/$defs/ComparisonTableState"
@@ -26,23 +45,28 @@
   "$defs": {
     "ComparisonTableState": {
       "title": "ComparisonTableState",
-      "description": "The comparison data to render. Contains a list of products with their attribute values and the attribute descriptors defining the columns.",
+      "description": "The comparison content owned by the backend: the table heading, the AI summary text, the compared products, and the ordered attribute descriptors defining the comparison rows.",
       "type": "object",
-      "required": [
-        "products",
-        "attributes"
-      ],
+      "required": ["products", "attributes", "heading", "summary"],
       "properties": {
+        "heading": {
+          "type": "string",
+          "description": "Title displayed above the comparison table."
+        },
+        "summary": {
+          "type": "string",
+          "description": "AI-generated summary text displayed below the comparison table."
+        },
         "products": {
           "type": "array",
-          "description": "Products to compare, each with attribute values keyed by attribute key.",
+          "description": "The compared products shown as columns of the comparison table.",
           "items": {
             "$ref": "https://schema.thermidor.coveo.com/definitions/comparison-product.schema.json"
           }
         },
         "attributes": {
           "type": "array",
-          "description": "Attribute descriptors defining the comparison columns.",
+          "description": "Attribute descriptors defining the comparison rows.",
           "items": {
             "$ref": "https://schema.thermidor.coveo.com/definitions/comparison-attribute.schema.json"
           }
@@ -51,4 +75,4 @@
       "additionalProperties": false
     }
   }
-}
+}

package/schema/components/date-facet.schema.json

@@ -9,9 +9,40 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "date-facet"
+      "const": "DateFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The commerce index field the facet operates on, bound to /state/<id>/field."
+    },
+    "displayName": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The facet's human-readable label, bound to /state/<id>/displayName."
+    },
+    "values": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The date-range facet values, bound to /state/<id>/values."
+    },
+    "customRange": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The custom range, bound to /state/<id>/customRange."
+    },
+    "hasActiveValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether at least one facet value is active, bound to /state/<id>/hasActiveValues."
+    },
+    "canShowMoreValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether more facet values can be shown, bound to /state/<id>/canShowMoreValues."
+    },
+    "canShowLessValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether fewer facet values can be shown, bound to /state/<id>/canShowLessValues."
     },
     "state": {
       "$ref": "#/$defs/DateFacetState"
@@ -110,12 +141,7 @@
       "title": "DateFacetValue",
       "description": "A single selectable date range within a date facet.",
       "type": "object",
-      "required": [
-        "start",
-        "end",
-        "numberOfResults",
-        "state"
-      ],
+      "required": ["start", "end", "numberOfResults", "state"],
       "properties": {
         "start": {
           "type": "string",
@@ -141,11 +167,7 @@
       "title": "DateFacetCustomRange",
       "description": "A custom date range applied by the user, with its result count.",
       "type": "object",
-      "required": [
-        "start",
-        "end",
-        "numberOfResults"
-      ],
+      "required": ["start", "end", "numberOfResults"],
       "properties": {
         "start": {
           "type": "string",
@@ -174,10 +196,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "start",
-            "end"
-          ],
+          "required": ["start", "end"],
           "properties": {
             "start": {
               "type": "string",
@@ -203,10 +222,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "start",
-            "end"
-          ],
+          "required": ["start", "end"],
           "properties": {
             "start": {
               "type": "string",
@@ -241,10 +257,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "start",
-            "end"
-          ],
+          "required": ["start", "end"],
           "properties": {
             "start": {
               "type": "string",
@@ -278,4 +291,4 @@
       ]
     }
   }
-}
+}