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

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

@@ -0,0 +1,385 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/regular-facet.schema.json",
+  "title": "RegularFacet",
+  "description": "Provides a string/specific-value facet for a commerce search surface. Renders selectable facet values, supports facet search, and dispatches value-selection, facet-search, and show-more/less actions.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "regular-facet"
+    },
+    "state": {
+      "$ref": "#/$defs/RegularFacetState"
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "toggleSelect",
+        "toggleExclude",
+        "toggleSingleSelect",
+        "toggleSingleExclude",
+        "clearAllActiveValues",
+        "search",
+        "showMoreSearchResults",
+        "clearSearch",
+        "showMoreValues",
+        "showLessValues"
+      ],
+      "properties": {
+        "toggleSelect": {
+          "$ref": "#/$defs/RegularFacetToggleSelectAction"
+        },
+        "toggleExclude": {
+          "$ref": "#/$defs/RegularFacetToggleExcludeAction"
+        },
+        "toggleSingleSelect": {
+          "$ref": "#/$defs/RegularFacetToggleSingleSelectAction"
+        },
+        "toggleSingleExclude": {
+          "$ref": "#/$defs/RegularFacetToggleSingleExcludeAction"
+        },
+        "clearAllActiveValues": {
+          "$ref": "#/$defs/RegularFacetClearAllActiveValuesAction"
+        },
+        "search": {
+          "$ref": "#/$defs/RegularFacetSearchAction"
+        },
+        "showMoreSearchResults": {
+          "$ref": "#/$defs/RegularFacetShowMoreSearchResultsAction"
+        },
+        "clearSearch": {
+          "$ref": "#/$defs/RegularFacetClearSearchAction"
+        },
+        "showMoreValues": {
+          "$ref": "#/$defs/RegularFacetShowMoreValuesAction"
+        },
+        "showLessValues": {
+          "$ref": "#/$defs/RegularFacetShowLessValuesAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "RegularFacetState": {
+      "title": "RegularFacetState",
+      "description": "The current regular facet state. Owned exclusively by the backend.",
+      "type": "object",
+      "required": [
+        "field",
+        "displayName",
+        "values",
+        "hasActiveValues",
+        "canShowMoreValues",
+        "canShowLessValues",
+        "facetSearch"
+      ],
+      "properties": {
+        "field": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "The index field the facet is built on."
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255,
+          "description": "Human-readable name for the facet."
+        },
+        "values": {
+          "type": "array",
+          "minItems": 0,
+          "maxItems": 1000,
+          "description": "The facet values available for selection.",
+          "items": {
+            "$ref": "#/$defs/RegularFacetValue"
+          }
+        },
+        "hasActiveValues": {
+          "type": "boolean",
+          "description": "Whether at least one facet value is not in the idle state (i.e. selected or excluded)."
+        },
+        "canShowMoreValues": {
+          "type": "boolean",
+          "description": "Whether more facet values can be shown."
+        },
+        "canShowLessValues": {
+          "type": "boolean",
+          "description": "Whether fewer facet values can be shown."
+        },
+        "facetSearch": {
+          "$ref": "#/$defs/RegularFacetSearch",
+          "description": "The current facet search state."
+        }
+      },
+      "additionalProperties": false
+    },
+    "RegularFacetValue": {
+      "title": "RegularFacetValue",
+      "description": "A single selectable value within a regular facet.",
+      "type": "object",
+      "required": [
+        "value",
+        "numberOfResults",
+        "state"
+      ],
+      "properties": {
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "The raw facet value."
+        },
+        "numberOfResults": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 999999999,
+          "description": "The number of results matching this facet value."
+        },
+        "state": {
+          "$ref": "https://schema.thermidor.coveo.com/definitions/facet-value-state.schema.json",
+          "description": "The selection state of this facet value."
+        }
+      },
+      "additionalProperties": false
+    },
+    "RegularFacetSearch": {
+      "title": "RegularFacetSearch",
+      "description": "The facet search state for a regular facet.",
+      "type": "object",
+      "required": [
+        "query",
+        "canShowMoreResults",
+        "results"
+      ],
+      "properties": {
+        "query": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 1024,
+          "description": "The current facet search query."
+        },
+        "canShowMoreResults": {
+          "type": "boolean",
+          "description": "Whether more facet search results can be shown for the current query."
+        },
+        "results": {
+          "type": "array",
+          "minItems": 0,
+          "maxItems": 1000,
+          "description": "The current facet search results.",
+          "items": {
+            "$ref": "#/$defs/RegularFacetSearchResult"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "RegularFacetSearchResult": {
+      "title": "RegularFacetSearchResult",
+      "description": "A single result returned by a regular facet search. Facet search only returns idle (unselected) values, so it carries no selection state.",
+      "type": "object",
+      "required": [
+        "value",
+        "numberOfResults"
+      ],
+      "properties": {
+        "value": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024,
+          "description": "The raw facet value. Pass this to toggleSelect/toggleExclude to act on it."
+        },
+        "numberOfResults": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 999999999,
+          "description": "The number of results matching this facet search value."
+        }
+      },
+      "additionalProperties": false
+    },
+    "RegularFacetToggleSelectAction": {
+      "title": "regularFacetToggleSelect",
+      "description": "Toggles the selected state of a facet value.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": [
+            "value"
+          ],
+          "properties": {
+            "value": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "description": "The raw facet value to toggle selection for."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "RegularFacetToggleExcludeAction": {
+      "title": "regularFacetToggleExclude",
+      "description": "Toggles the excluded state of a facet value.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": [
+            "value"
+          ],
+          "properties": {
+            "value": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "description": "The raw facet value to toggle exclusion for."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "RegularFacetToggleSingleSelectAction": {
+      "title": "regularFacetToggleSingleSelect",
+      "description": "Toggles the selected state of a facet value, deselecting all other values (single-select behavior).",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": [
+            "value"
+          ],
+          "properties": {
+            "value": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "description": "The raw facet value to single-select."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "RegularFacetToggleSingleExcludeAction": {
+      "title": "regularFacetToggleSingleExclude",
+      "description": "Toggles the excluded state of a facet value, clearing all other selections/exclusions (single-exclude behavior).",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": [
+            "value"
+          ],
+          "properties": {
+            "value": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 1024,
+              "description": "The raw facet value to single-exclude."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "RegularFacetClearAllActiveValuesAction": {
+      "title": "regularFacetClearAllActiveValues",
+      "description": "Resets all facet values to the idle state, clearing every selection and exclusion.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "RegularFacetSearchAction": {
+      "title": "search",
+      "description": "Runs a facet search with the given query.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": [
+            "query"
+          ],
+          "properties": {
+            "query": {
+              "type": "string",
+              "minLength": 0,
+              "maxLength": 1024,
+              "description": "The facet search query to run."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "RegularFacetShowMoreSearchResultsAction": {
+      "title": "regularFacetShowMoreSearchResults",
+      "description": "Requests the next page of facet search results for the current query.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "RegularFacetClearSearchAction": {
+      "title": "regularFacetClearSearch",
+      "description": "Clears the facet search query and results.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "RegularFacetShowMoreValuesAction": {
+      "title": "showMoreValues",
+      "description": "Increases the number of facet values shown.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    },
+    "RegularFacetShowLessValuesAction": {
+      "title": "showLessValues",
+      "description": "Decreases the number of facet values shown.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/search-box.schema.json",
+  "title": "SearchBox",
+  "description": "Provides a search input for a commerce search surface. Renders the current query and dispatches submitQuery when the user submits a new query.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "search-box"
+    },
+    "state": {
+      "$ref": "#/$defs/SearchBoxState"
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "submitQuery"
+      ],
+      "properties": {
+        "submitQuery": {
+          "$ref": "#/$defs/SubmitQueryAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "SearchBoxState": {
+      "title": "SearchBoxState",
+      "description": "The current search box state. Owned exclusively by the backend.",
+      "type": "object",
+      "required": [
+        "query"
+      ],
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "The current search query string."
+        }
+      },
+      "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
+        }
+      }
+    }
+  }
+}

package/schema/components/sort.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/sort.schema.json",
+  "title": "Sort",
+  "description": "Provides sort controls for a commerce search surface. Renders available sort options and dispatches selectSort when the user changes the sort order.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "componentType": {
+      "type": "string",
+      "const": "sort"
+    },
+    "state": {
+      "$ref": "#/$defs/SortState"
+    },
+    "actions": {
+      "type": "object",
+      "required": [
+        "selectSort"
+      ],
+      "properties": {
+        "selectSort": {
+          "$ref": "#/$defs/SelectSortAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "SortState": {
+      "title": "SortState",
+      "description": "The current sort state. Owned exclusively by the backend.",
+      "type": "object",
+      "required": [
+        "appliedSort",
+        "availableSorts"
+      ],
+      "properties": {
+        "appliedSort": {
+          "$ref": "#/$defs/SortCriterion",
+          "description": "The currently applied sort criterion."
+        },
+        "availableSorts": {
+          "type": "array",
+          "description": "All available sort options.",
+          "items": {
+            "$ref": "#/$defs/SortCriterion"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "SortCriterion": {
+      "title": "SortCriterion",
+      "description": "A sort criterion consisting of a named criteria and field definitions.",
+      "type": "object",
+      "required": [
+        "sortCriteria",
+        "fields"
+      ],
+      "properties": {
+        "sortCriteria": {
+          "type": "string",
+          "description": "The name of the sort criterion (e.g. 'relevance', 'price asc')."
+        },
+        "fields": {
+          "type": "array",
+          "description": "The fields involved in this sort criterion."
+        }
+      },
+      "additionalProperties": false
+    },
+    "SelectSortAction": {
+      "title": "selectSort",
+      "description": "Applies a new sort criterion.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": [
+            "sortCriteria",
+            "fields"
+          ],
+          "properties": {
+            "sortCriteria": {
+              "type": "string",
+              "description": "The sort criterion to apply."
+            },
+            "fields": {
+              "type": "array",
+              "description": "The fields involved in the sort criterion."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    }
+  }
+}

package/schema/definitions/action-item.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/definitions/action-item.schema.json",
+  "title": "ActionItem",
+  "description": "A suggested action the assistant offers the user, such as a follow-up question or a search query.",
+  "type": "object",
+  "required": ["text", "type"],
+  "properties": {
+    "text": {
+      "type": "string",
+      "description": "The display text of the action shown to the user."
+    },
+    "type": {
+      "type": "string",
+      "enum": ["followup", "search"],
+      "description": "The kind of action: \"followup\" triggers a conversational follow-up, \"search\" triggers a standalone search."
+    }
+  },
+  "additionalProperties": false
+}

package/schema/definitions/bundle-tier.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/definitions/bundle-tier.schema.json",
+  "title": "BundleTier",
+  "description": "A tier in a product bundle, grouping product slots by price/quality level.",
+  "type": "object",
+  "required": ["label", "description", "slots"],
+  "properties": {
+    "label": {
+      "type": "string",
+      "description": "Display label for the tier (e.g. 'Budget')."
+    },
+    "description": {
+      "type": "string",
+      "description": "Brief description of what the tier includes."
+    },
+    "slots": {
+      "type": "array",
+      "description": "Product category slots within this tier.",
+      "items": {
+        "$ref": "#/$defs/BundleSlot"
+      }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "BundleSlot": {
+      "title": "BundleSlot",
+      "type": "object",
+      "required": ["categoryLabel", "surfaceRef"],
+      "properties": {
+        "categoryLabel": {
+          "type": "string",
+          "description": "Display name of the product category for this slot."
+        },
+        "surfaceRef": {
+          "type": "string",
+          "description": "Surface ID where this slot's products are rendered via a ProductCarousel."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/definitions/cart-item.schema.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/definitions/cart-item.schema.json",
+  "title": "CartItem",
+  "description": "A single line item in the cart, as exposed by the CartController state and used in cart action payloads.",
+  "type": "object",
+  "required": ["productId", "name", "price", "quantity"],
+  "properties": {
+    "productId": {
+      "type": "string",
+      "description": "The unique product identifier. Corresponds to the Product's permanentid field."
+    },
+    "name": {
+      "type": "string",
+      "description": "The display name of the product at the time it was added to the cart."
+    },
+    "price": {
+      "type": "number",
+      "minimum": 0,
+      "description": "The non-negative unit price at the time the item was added, in the session currency."
+    },
+    "quantity": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The number of units of this product in the cart."
+    }
+  },
+  "additionalProperties": false
+}

package/schema/definitions/comparison-attribute.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/definitions/comparison-attribute.schema.json",
+  "title": "ComparisonAttribute",
+  "description": "Defines an attribute (column) used in a ComparisonTable. The key is the programmatic identifier that maps to values in ComparisonProduct.values, and label is the human-readable column heading.",
+  "type": "object",
+  "required": ["key", "label"],
+  "properties": {
+    "key": {
+      "type": "string",
+      "description": "The programmatic identifier for this attribute, used as a key in ComparisonProduct.values."
+    },
+    "label": {
+      "type": "string",
+      "description": "The human-readable column heading displayed in the comparison table."
+    }
+  },
+  "additionalProperties": false
+}