@magicx-eng/ai-autocomplete-vanilla 0.34.0 → 0.36.0

package/README.md

@@ -59,7 +59,7 @@ const ac = new AIAutocomplete(document.getElementById("root"), {
   onSubmit: (result) => {
     console.log(result.query);            // "Create a email"
     console.log(result.raw_query);        // "Create a {{TASK_1}}"
-    console.log(result.completed_params); // [{ placeholder: "{{TASK_1}}", type: "task", ... }]
+    console.log(result.completed_params); // [{ placeholder: "{{TASK_1}}", parameter: "task", ... }]
   },
 });
 ```
@@ -202,7 +202,10 @@ Each server item becomes a `Product` with `id` (the item's stable id), `title`,
 currency is yours to add), `vendor`, `imageUrl`, and a `url`: the item's own
 `item_url` when the uploaded catalog named one (absolute or root-relative;
 anything else is ignored), else a **relative** `/products/{handle}` — the right
-link for a Shopify widget running on the storefront itself. An item with
+link for a Shopify widget running on the storefront itself — opened on the
+variant the query chose (`?variant=…`, e.g. the blue one for "blue shoes") when
+there is one, whose price and image the card then shows. `available` is carried
+over when the server reports it. An item with
 neither gets no `url`: its card is still activatable and still emits
 `onProductSelect`, it just has nothing for cmd-click to open. `productFromMatchedItem` / `productsFromCustomFields` are
 exported for a hand-rolled strip that wants the same mapping.
@@ -229,6 +232,17 @@ empty or whitespace-only title shows `?`. The fallback works in both row and
 list layouts. Initial tiles are decorative (`aria-hidden="true"`); the card's
 visible title supplies its text.
 
+**Sold out.** A product with `available: false` shows a "Sold out" badge over
+the top-left of its image (in the list layout, a smaller banner across the
+bottom of the thumbnail) and its image is desaturated; the card stays
+selectable and keeps its link. Absent or `true` shows no
+badge, so leave `available` out when you don't know. The badge is part of the
+card's text, so screen readers announce it. Theme it with
+`--aia-product-badge-bg`, `--aia-product-badge-color`,
+`--aia-product-badge-font-size` and `--aia-product-badge-inset`, and the list
+banner with `--aia-product-badge-list-bg`, `--aia-product-badge-list-color` and
+`--aia-product-badge-list-font-size`.
+
 Set the option at construction or change it through `update()`. Both
 rendered tiers (`"full"` and `"dropdown"`) apply it to the visible cards:
 
@@ -269,7 +283,7 @@ ac.subscribe((state) => {
   if (!report) return;                         // no catalog was read for this response
   count.textContent = `${report.items.total} results`;
   if (report.dropped_filters.length > 0) {
-    // e.g. { param: "Color", value: "Chartreuse", op: "eq" } — the shopper asked
+    // e.g. { parameter: "Color", value: "Chartreuse", op: "eq" } — the shopper asked
     // for a colour no item carries, so the results ignore it. Say so.
     note.textContent = `No match for ${report.dropped_filters.map((f) => f.value).join(", ")}`;
   }
@@ -277,7 +291,7 @@ ac.subscribe((state) => {
 ```
 
 - `applied_filters` / `dropped_filters` — the constraints the server read out
-  of the query as `{ param, value, op }` (`op` is one of `eq`, `ne`, `lt`,
+  of the query as `{ parameter, value, op }` (`op` is one of `eq`, `ne`, `lt`,
   `lte`, `gt`, `gte`), split into the ones the catalog answered and the ones it
   could not (a parameter it does not have, a bound that is not a number, a
   value no item carries). The items answer the applied set, so the dropped
@@ -340,7 +354,7 @@ new AIAutocomplete(container, {
 });
 ```
 
-`Product` is exactly six fields; only `id` and `title` are required:
+`Product` is exactly seven fields; only `id` and `title` are required:
 
 ```ts
 type Product = {
@@ -350,6 +364,7 @@ type Product = {
   imageUrl?: string | null;   // null uses the configured productImageFallback
   price?: string;             // pre-formatted by you
   vendor?: string;
+  available?: boolean;        // false shows a "Sold out" badge
 };
 ```
 
@@ -736,9 +751,9 @@ The structured query as the SDK currently understands it. The same object is pas
 | `query` | `string` | Plain text as the user sees it, trimmed. |
 | `raw_query` | `string` | `query` with each completed param replaced by its placeholder token (e.g. `"Create a {{TASK_1}}"`). |
 | `completed_params` | `CompletedParam[]` | Filled parameter values in query order, followed by any the user skipped (see below). |
-| `identified_params` | `IdentifiedParam[]` | Parameters the server recognised in the user's own words, as `{ type, value }` — e.g. `{ type: "due_date", value: "Friday" }` when the user typed "by Friday" instead of picking a date. They are not tokenized in `raw_query`, and they are tentative: each response replaces the set, and an entry drops out as soon as its text is edited away. |
+| `identified_params` | `IdentifiedParam[]` | Parameters the server recognised in the user's own words, as `{ parameter, text }` — e.g. `{ parameter: "due_date", text: "Friday" }` when the user typed "by Friday" instead of picking a date. They are not tokenized in `raw_query`, and they are tentative: each response replaces the set, and an entry drops out as soon as its text is edited away. |
 | `is_ready` | `boolean` | Whether the server considers the query complete enough to act on. |
-| `custom_fields?` | `CustomFieldsReport` | What catalog grounding did for the latest applied response, when it read a catalog at all — see [Product strip](#product-strip). `applied_filters` and `dropped_filters` list the query's constraints as `{ param, value, op }`; `items.total` is how many items the applied ones left standing and `items.matched` the ones the strip renders. Absent (no key) when the response carried no report. |
+| `custom_fields?` | `CustomFieldsReport` | What catalog grounding did for the latest applied response, when it read a catalog at all — see [Product strip](#product-strip). `applied_filters` and `dropped_filters` list the query's constraints as `{ parameter, value, op }`; `items.total` is how many items the applied ones left standing and `items.matched` the ones the strip renders. Absent (no key) when the response carried no report. |
 
 #### Reading the query as it's built
 
@@ -772,12 +787,12 @@ What "every successful round-trip" means in practice:
 Pressing <kbd>→</kbd> at the end of the input dismisses the active pill. The dismissal is reported to the server — and included in `completed_params` here — as an entry with no placeholder and the sentinel text `"skipped"`:
 
 ```ts
-{ placeholder: "", type: "goal", text: "skipped", kind: null }
+{ placeholder: "", parameter: "goal", text: "skipped", kind: null }
 ```
 
-Skipped entries are appended after the filled params (they have no position in the query) and are deduped by type. A skip is dropped if a param of the same type ends up filled anyway. Skipping the last available pill triggers an immediate request so the server can suggest something else; earlier skips ride along on the next request. `reset()` clears them.
+Skipped entries are appended after the filled params (they have no position in the query) and are deduped by parameter. A skip is dropped if a param of the same parameter ends up filled anyway. Skipping the last available pill triggers an immediate request so the server can suggest something else; earlier skips ride along on the next request. `reset()` clears them.
 
-> **Reading `state.skippedParams` directly:** the array is append-only until `reset()`. The "drop a skip whose type got filled" rule is applied when the payload is built, not by pruning the array — so if the user skips `goal` and later fills one, the raw array still holds the `goal` entry. That's deliberate: the filter self-heals if they then delete that param's text, where pruning would discard the signal for good. Apply the same rule yourself with the exported `withSkippedParams(completedParams, skippedParams)`.
+> **Reading `state.skippedParams` directly:** the array is append-only until `reset()`. The "drop a skip whose parameter got filled" rule is applied when the payload is built, not by pruning the array — so if the user skips `goal` and later fills one, the raw array still holds the `goal` entry. That's deliberate: the filter self-heals if they then delete that param's text, where pruning would discard the signal for good. Apply the same rule yourself with the exported `withSkippedParams(completedParams, skippedParams)`.
 
 ### Event Subscription
 
@@ -992,7 +1007,7 @@ Submits from Enter and from the built-in submit button are recorded for you. If
 
 ## Option Overrides
 
-Supply the options for a parameter yourself instead of taking the server's. Each entry is keyed by the suggestion `type` and is a function of the phrase the user has typed for that parameter:
+Supply the options for a parameter yourself instead of taking the server's. Each entry is keyed by the suggestion `parameter` and is a function of the phrase the user has typed for that parameter:
 
 ```ts
 new AIAutocomplete(el, {
@@ -1013,11 +1028,11 @@ new AIAutocomplete(el, {
 });
 ```
 
-**When it's called.** Once the moment the parameter becomes active — a response suggests it, a skip or a selection moves it to the front, or the user taps a completed value of that type to change it — with whatever they have already typed for it (usually `""`, the request for the default list). Then again on the SDK's typing debounce with each new phrase, so you can run a search or page through a larger list. If a phrase is already covered by what you last returned, return that list again. The third argument is the `Suggestion` being answered, for the rare override that serves more than one type.
+**When it's called.** Once the moment the parameter becomes active — a response suggests it, a skip or a selection moves it to the front, or the user taps a completed value of that parameter to change it — with whatever they have already typed for it (usually `""`, the request for the default list). Then again on the SDK's typing debounce with each new phrase, so you can run a search or page through a larger list. If a phrase is already covered by what you last returned, return that list again. The third argument is the `Suggestion` being answered, for the rare override that serves more than one parameter.
 
 **What's shown.** Your answer, as-is: it is not filtered again by the phrase it was produced for, so a fuzzy or synonym match survives. Between two calls the previous answer is filtered locally by what the user types, so the list reacts to every keystroke. Typing the full text of an option in the answer completes the parameter, exactly as it does for a server option.
 
-**The server's role.** The server's own options for an overridden type are never shown. While an override owns the active parameter the server is not asked for suggestions; it is asked again when the parameter is answered or skipped. Return an empty list for a typed phrase and the SDK falls back to the server for that phrase — the typed text goes out the way it does for a parameter with no matching options — and won't ask you the same phrase twice. An empty list for `""` leaves the parameter on screen with no options.
+**The server's role.** The server's own options for an overridden parameter are never shown. While an override owns the active parameter the server is not asked for suggestions; it is asked again when the parameter is answered or skipped. Return an empty list for a typed phrase and the SDK falls back to the server for that phrase — the typed text goes out the way it does for a parameter with no matching options — and won't ask you the same phrase twice. An empty list for `""` leaves the parameter on screen with no options.
 
 **Cancellation and errors.** Honour `signal`: it is aborted when a newer phrase supersedes the call, when the parameter stops being active, and on `destroy()`. A throw or a rejection is logged once per instance and treated as an empty answer, never as a fetch error.
 

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 type TaskKind = "automation" | "email" | "insight";
 interface CompletedParam {
     placeholder: string;
-    type: string;
+    parameter: string;
     text?: string;
     kind: TaskKind | null;
 }
@@ -49,15 +49,34 @@ interface SuggestionOption {
     is_tappable: boolean;
     kind: TaskKind | null;
     metadata?: Record<string, unknown>;
+    /**
+     * The parameter a tap on this option answers. The server names it on every
+     * option; options the SDK builds itself (a calendar's dates) carry their
+     * suggestion's.
+     */
+    parameter?: string;
+}
+/**
+ * The value type of a suggestion's parameter — which picker it needs. Present
+ * only for a date or date-range parameter.
+ */
+interface SuggestionType {
+    kind: "string" | "numeric" | "date" | "date_range" | "boolean";
+    /** How a date is written, e.g. "DD/MM/YYYY". */
+    date_format?: string;
+    /** What joins the two dates of a range, e.g. " to ". */
+    separator?: string;
+    unit?: string;
 }
 interface Suggestion {
-    type: string;
+    parameter: string;
     text: string;
     required: boolean;
     options?: SuggestionOption[];
+    type?: SuggestionType;
 }
 interface InputItem {
-    type: string;
+    parameter: string;
     text: string;
     state: "completed" | "in_progress";
     /** Absent or "selected" = echo of client params; "identified" = LLM-inferred. */
@@ -65,15 +84,15 @@ interface InputItem {
 }
 /** Wire shape for an LLM-identified param echoed back to the server. */
 interface IdentifiedParam {
-    type: string;
-    value: string;
+    parameter: string;
+    text: string;
 }
 /**
  * Wire shape for a recently-suggested hint entry: a suggestion that was on
  * screen when the user started typing the current unresolved trailing text.
  */
 interface RecentlySuggested {
-    type: string;
+    parameter: string;
     text: string;
 }
 interface AutocompleteRequest {
@@ -92,6 +111,8 @@ interface AutocompleteRequest {
         client_version: string;
         session_id: string;
         source?: "full-sdk" | "headless-sdk";
+        /** The wire format this SDK speaks ({@link SCHEMA_VERSION}). */
+        schema_version: string;
     };
 }
 interface AutocompleteResponse {
@@ -111,6 +132,8 @@ interface AutocompleteResponse {
         request_at: string;
         /** The server's funnel-telemetry switch. Absent means off: send no funnel events. */
         funnel_telemetry?: boolean;
+        /** The request's `schema_version`, echoed back. */
+        schema_version?: string;
     };
 }
 /** Comparison an {@link ExpressedFilter} applies to its value. */
@@ -120,7 +143,7 @@ type FilterOp = "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
  * how the two compare ("price", "100", "lt").
  */
 interface ExpressedFilter {
-    param: string;
+    parameter: string;
     value: string;
     op: FilterOp;
 }
@@ -154,6 +177,18 @@ interface MatchedItem {
      * item carries `handle` instead. When both are present the strip links here.
      */
     item_url?: string;
+    /**
+     * The variant a filter in the query chose for this item ("blue", "size 10"),
+     * as the platform's numeric variant id. When set, `price` and `image_url`
+     * are that variant's, and the strip links to `/products/{handle}?variant=…`
+     * so the shopper lands on it.
+     */
+    variant_id?: string;
+    /**
+     * Whether the item can be bought: `false` is sold out. Absent when the
+     * catalog doesn't say, which is not the same as sold out.
+     */
+    available?: boolean;
 }
 /** The items the applied filters left standing. */
 interface MatchedItems {
@@ -201,8 +236,13 @@ interface CompletedParamState extends CompletedParam {
     text: string;
     /** The originating option's `value` (see {@link SuggestionOption.value}), carried over so `toWireParam` can send it instead of the shortened `text`. */
     value?: string;
-    /** Source suggestion's `type` — used by re-edit mode to render the dropdown pill. */
-    suggestionType: string;
+    /** Source suggestion's `parameter` — used by re-edit mode to render the dropdown pill. */
+    suggestionParameter: string;
+    /**
+     * Source suggestion's `type` (its value type), carried so re-edit opens the
+     * same picker the first pick did — see {@link Suggestion.type}.
+     */
+    suggestionValueType?: SuggestionType;
     /** Source suggestion's `text` — used by re-edit mode to render the dropdown pill. */
     suggestionPlaceholder: string;
     /** Cached options from the suggestion that produced this param — re-edit shows these. */
@@ -241,8 +281,8 @@ interface CompletedParamState extends CompletedParam {
  */
 interface SkippedParamState {
     id: string;
-    /** The skipped suggestion's `type` (e.g. "goal"). */
-    type: string;
+    /** The skipped suggestion's `parameter` (e.g. "goal"). */
+    parameter: string;
     /** The suggestion's display text at skip time. Introspection only — never sent. */
     suggestionPlaceholder: string;
 }
@@ -253,7 +293,7 @@ interface SkippedParamState {
  */
 interface IdentifiedParamState {
     id: string;
-    type: string;
+    parameter: string;
     text: string;
 }
 type Segment = {
@@ -352,6 +392,12 @@ interface Product {
     /** Pre-formatted by the integration, which is the side that knows the currency. */
     price?: string;
     vendor?: string;
+    /**
+     * `false` marks the card sold out: a "Sold out" badge over the image, and
+     * the image desaturated. The card stays selectable. Absent or `true` shows no
+     * badge — leave it out when availability is unknown.
+     */
+    available?: boolean;
 }
 /**
  * How the product strip lays its cards out. `"row"` is the horizontally
@@ -562,12 +608,15 @@ declare function isCalendarFormat(format: FormatType): boolean;
  * them. A parameter called `travel_date` whose options are all spans is a span
  * parameter, whatever its name says.
  *
- * Accepts anything with a `type`, not a `Suggestion`, so re-edit can ask the
- * same question about a completed param via its `suggestionType`.
+ * Accepts anything with a `parameter`, not a `Suggestion`, so re-edit can ask
+ * the same question about a completed param via its `suggestionParameter`.
+ * A suggestion whose `type` names a date or date-range parameter is that,
+ * whatever its options and name say.
  */
 declare function resolveFormatType(source: {
-    type: string;
+    parameter: string;
     options?: SuggestionOption[];
+    type?: SuggestionType;
 } | undefined | null): FormatType;
 
 /**
@@ -636,7 +685,7 @@ interface CoreInputState {
      * owns the pill on screen. Owned by `OptionSourceController`.
      */
     optionSearch: {
-        type: string;
+        parameter: string;
         query: string;
         status: "loading" | "done";
     } | null;
@@ -739,7 +788,7 @@ interface CoreInputState {
     editingIdentified: {
         id: string;
         /** The identified param's type, which the committed param inherits. */
-        type: string;
+        parameter: string;
         /** Plain-text offsets bounding the span being replaced. */
         anchor: number;
         tail: number;
@@ -1251,7 +1300,7 @@ declare class AIAutocomplete {
      * The skipped suggestion is recorded in `skippedParams` so every subsequent
      * request (and the submit result) carries it as a `completed_params` entry
      * with `text: "skipped"` — otherwise the server has no way to know the user
-     * declined it and keeps suggesting the same parameter. Deduped by type: the
+     * declined it and keeps suggesting the same parameter. Deduped by parameter: the
      * same type skipped twice is one entry.
      *
      * When the last pill is removed there are no options left to show, so the
@@ -2109,6 +2158,12 @@ interface Store<S> {
 }
 declare function createStore<S>(initial: S): Store<S>;
 
+/**
+ * The /suggest wire format this SDK speaks, sent as `meta.schema_version` on
+ * every request. The server answers in the same format.
+ */
+declare const SCHEMA_VERSION = "1.0";
+
 /** Base URL for the "AI Autocomplete" branding/attribution link in the dropdown footer. */
 declare const ATTRIBUTION_URL = "https://ai-autocomplete.com";
 /**
@@ -2160,7 +2215,7 @@ declare function getFooterHint(optionHighlighted: boolean, isInputEmpty: boolean
 /**
  * Projects client-side identified-param state onto its wire shape.
  *
- * The one place the `{ type, value }` form is spelled out. Both the request
+ * The one place the `{ parameter, text }` form is spelled out. Both the request
  * body (`api.ts`) and the `AutocompleteResult` handed to `onResult` /
  * `onSubmit` go through it, so the params the consumer receives are exactly
  * the ones the server was told about.
@@ -2181,9 +2236,10 @@ declare const PRODUCT_PATH_PREFIX = "/products/";
  * `customFields` gets the same cards the built-in one draws.
  *
  * The link is the item's own `item_url` when the catalog named one, else the
- * `/products/{handle}` path a Shopify item implies. An item with neither
- * yields a card without a `url`: still activatable, still emitting
- * `onProductSelect`, just nothing for cmd-click to open.
+ * `/products/{handle}` path a Shopify item implies, opened on the chosen
+ * variant when there is one. An item with neither yields a card without a
+ * `url`: still activatable, still emitting `onProductSelect`, just nothing for
+ * cmd-click to open.
  */
 declare function productFromMatchedItem(item: MatchedItem): Product;
 /**
@@ -2299,4 +2355,4 @@ interface SubmitResultExtras {
  */
 declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[], extras?: SubmitResultExtras): AutocompleteResult;
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverride, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverride, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCHEMA_VERSION, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type SuggestionType, type TaskKind, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 type TaskKind = "automation" | "email" | "insight";
 interface CompletedParam {
     placeholder: string;
-    type: string;
+    parameter: string;
     text?: string;
     kind: TaskKind | null;
 }
@@ -49,15 +49,34 @@ interface SuggestionOption {
     is_tappable: boolean;
     kind: TaskKind | null;
     metadata?: Record<string, unknown>;
+    /**
+     * The parameter a tap on this option answers. The server names it on every
+     * option; options the SDK builds itself (a calendar's dates) carry their
+     * suggestion's.
+     */
+    parameter?: string;
+}
+/**
+ * The value type of a suggestion's parameter — which picker it needs. Present
+ * only for a date or date-range parameter.
+ */
+interface SuggestionType {
+    kind: "string" | "numeric" | "date" | "date_range" | "boolean";
+    /** How a date is written, e.g. "DD/MM/YYYY". */
+    date_format?: string;
+    /** What joins the two dates of a range, e.g. " to ". */
+    separator?: string;
+    unit?: string;
 }
 interface Suggestion {
-    type: string;
+    parameter: string;
     text: string;
     required: boolean;
     options?: SuggestionOption[];
+    type?: SuggestionType;
 }
 interface InputItem {
-    type: string;
+    parameter: string;
     text: string;
     state: "completed" | "in_progress";
     /** Absent or "selected" = echo of client params; "identified" = LLM-inferred. */
@@ -65,15 +84,15 @@ interface InputItem {
 }
 /** Wire shape for an LLM-identified param echoed back to the server. */
 interface IdentifiedParam {
-    type: string;
-    value: string;
+    parameter: string;
+    text: string;
 }
 /**
  * Wire shape for a recently-suggested hint entry: a suggestion that was on
  * screen when the user started typing the current unresolved trailing text.
  */
 interface RecentlySuggested {
-    type: string;
+    parameter: string;
     text: string;
 }
 interface AutocompleteRequest {
@@ -92,6 +111,8 @@ interface AutocompleteRequest {
         client_version: string;
         session_id: string;
         source?: "full-sdk" | "headless-sdk";
+        /** The wire format this SDK speaks ({@link SCHEMA_VERSION}). */
+        schema_version: string;
     };
 }
 interface AutocompleteResponse {
@@ -111,6 +132,8 @@ interface AutocompleteResponse {
         request_at: string;
         /** The server's funnel-telemetry switch. Absent means off: send no funnel events. */
         funnel_telemetry?: boolean;
+        /** The request's `schema_version`, echoed back. */
+        schema_version?: string;
     };
 }
 /** Comparison an {@link ExpressedFilter} applies to its value. */
@@ -120,7 +143,7 @@ type FilterOp = "eq" | "ne" | "lt" | "lte" | "gt" | "gte";
  * how the two compare ("price", "100", "lt").
  */
 interface ExpressedFilter {
-    param: string;
+    parameter: string;
     value: string;
     op: FilterOp;
 }
@@ -154,6 +177,18 @@ interface MatchedItem {
      * item carries `handle` instead. When both are present the strip links here.
      */
     item_url?: string;
+    /**
+     * The variant a filter in the query chose for this item ("blue", "size 10"),
+     * as the platform's numeric variant id. When set, `price` and `image_url`
+     * are that variant's, and the strip links to `/products/{handle}?variant=…`
+     * so the shopper lands on it.
+     */
+    variant_id?: string;
+    /**
+     * Whether the item can be bought: `false` is sold out. Absent when the
+     * catalog doesn't say, which is not the same as sold out.
+     */
+    available?: boolean;
 }
 /** The items the applied filters left standing. */
 interface MatchedItems {
@@ -201,8 +236,13 @@ interface CompletedParamState extends CompletedParam {
     text: string;
     /** The originating option's `value` (see {@link SuggestionOption.value}), carried over so `toWireParam` can send it instead of the shortened `text`. */
     value?: string;
-    /** Source suggestion's `type` — used by re-edit mode to render the dropdown pill. */
-    suggestionType: string;
+    /** Source suggestion's `parameter` — used by re-edit mode to render the dropdown pill. */
+    suggestionParameter: string;
+    /**
+     * Source suggestion's `type` (its value type), carried so re-edit opens the
+     * same picker the first pick did — see {@link Suggestion.type}.
+     */
+    suggestionValueType?: SuggestionType;
     /** Source suggestion's `text` — used by re-edit mode to render the dropdown pill. */
     suggestionPlaceholder: string;
     /** Cached options from the suggestion that produced this param — re-edit shows these. */
@@ -241,8 +281,8 @@ interface CompletedParamState extends CompletedParam {
  */
 interface SkippedParamState {
     id: string;
-    /** The skipped suggestion's `type` (e.g. "goal"). */
-    type: string;
+    /** The skipped suggestion's `parameter` (e.g. "goal"). */
+    parameter: string;
     /** The suggestion's display text at skip time. Introspection only — never sent. */
     suggestionPlaceholder: string;
 }
@@ -253,7 +293,7 @@ interface SkippedParamState {
  */
 interface IdentifiedParamState {
     id: string;
-    type: string;
+    parameter: string;
     text: string;
 }
 type Segment = {
@@ -352,6 +392,12 @@ interface Product {
     /** Pre-formatted by the integration, which is the side that knows the currency. */
     price?: string;
     vendor?: string;
+    /**
+     * `false` marks the card sold out: a "Sold out" badge over the image, and
+     * the image desaturated. The card stays selectable. Absent or `true` shows no
+     * badge — leave it out when availability is unknown.
+     */
+    available?: boolean;
 }
 /**
  * How the product strip lays its cards out. `"row"` is the horizontally
@@ -562,12 +608,15 @@ declare function isCalendarFormat(format: FormatType): boolean;
  * them. A parameter called `travel_date` whose options are all spans is a span
  * parameter, whatever its name says.
  *
- * Accepts anything with a `type`, not a `Suggestion`, so re-edit can ask the
- * same question about a completed param via its `suggestionType`.
+ * Accepts anything with a `parameter`, not a `Suggestion`, so re-edit can ask
+ * the same question about a completed param via its `suggestionParameter`.
+ * A suggestion whose `type` names a date or date-range parameter is that,
+ * whatever its options and name say.
  */
 declare function resolveFormatType(source: {
-    type: string;
+    parameter: string;
     options?: SuggestionOption[];
+    type?: SuggestionType;
 } | undefined | null): FormatType;
 
 /**
@@ -636,7 +685,7 @@ interface CoreInputState {
      * owns the pill on screen. Owned by `OptionSourceController`.
      */
     optionSearch: {
-        type: string;
+        parameter: string;
         query: string;
         status: "loading" | "done";
     } | null;
@@ -739,7 +788,7 @@ interface CoreInputState {
     editingIdentified: {
         id: string;
         /** The identified param's type, which the committed param inherits. */
-        type: string;
+        parameter: string;
         /** Plain-text offsets bounding the span being replaced. */
         anchor: number;
         tail: number;
@@ -1251,7 +1300,7 @@ declare class AIAutocomplete {
      * The skipped suggestion is recorded in `skippedParams` so every subsequent
      * request (and the submit result) carries it as a `completed_params` entry
      * with `text: "skipped"` — otherwise the server has no way to know the user
-     * declined it and keeps suggesting the same parameter. Deduped by type: the
+     * declined it and keeps suggesting the same parameter. Deduped by parameter: the
      * same type skipped twice is one entry.
      *
      * When the last pill is removed there are no options left to show, so the
@@ -2109,6 +2158,12 @@ interface Store<S> {
 }
 declare function createStore<S>(initial: S): Store<S>;
 
+/**
+ * The /suggest wire format this SDK speaks, sent as `meta.schema_version` on
+ * every request. The server answers in the same format.
+ */
+declare const SCHEMA_VERSION = "1.0";
+
 /** Base URL for the "AI Autocomplete" branding/attribution link in the dropdown footer. */
 declare const ATTRIBUTION_URL = "https://ai-autocomplete.com";
 /**
@@ -2160,7 +2215,7 @@ declare function getFooterHint(optionHighlighted: boolean, isInputEmpty: boolean
 /**
  * Projects client-side identified-param state onto its wire shape.
  *
- * The one place the `{ type, value }` form is spelled out. Both the request
+ * The one place the `{ parameter, text }` form is spelled out. Both the request
  * body (`api.ts`) and the `AutocompleteResult` handed to `onResult` /
  * `onSubmit` go through it, so the params the consumer receives are exactly
  * the ones the server was told about.
@@ -2181,9 +2236,10 @@ declare const PRODUCT_PATH_PREFIX = "/products/";
  * `customFields` gets the same cards the built-in one draws.
  *
  * The link is the item's own `item_url` when the catalog named one, else the
- * `/products/{handle}` path a Shopify item implies. An item with neither
- * yields a card without a `url`: still activatable, still emitting
- * `onProductSelect`, just nothing for cmd-click to open.
+ * `/products/{handle}` path a Shopify item implies, opened on the chosen
+ * variant when there is one. An item with neither yields a card without a
+ * `url`: still activatable, still emitting `onProductSelect`, just nothing for
+ * cmd-click to open.
  */
 declare function productFromMatchedItem(item: MatchedItem): Product;
 /**
@@ -2299,4 +2355,4 @@ interface SubmitResultExtras {
  */
 declare function buildSubmitResult(text: string, completedParams: CompletedParamState[], skippedParams?: SkippedParamState[], extras?: SubmitResultExtras): AutocompleteResult;
 
-export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverride, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type TaskKind, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };
+export { AIAutocomplete, type APIConfig, type APIKeyConfig, ATTRIBUTION_URL, type AccessTokenConfig, type AccessTokenResult, type AppearanceMode, type AutocompleteRequest, type AutocompleteResponse, type AutocompleteResult, type CompletedParam, type CompletedParamState, type CoreOptions, type CoreState, type CustomFieldsReport, DATE_RANGE_META_END, DATE_RANGE_META_START, DEFAULT_OPTION_COUNT_UNIT, type DateMonthView, type DateRange, type DateSelection, type ExpressedFilter, type FilterOp, type FormatType, type IdentifiedParam, type IdentifiedParamState, type InputItem, type LooseDateOptions, type MatchedItem, type MatchedItems, ModeController, OPTIONS_GRID_MOBILE_QUERY, OPTION_ENTER_DELAY_VAR, OPTION_ENTER_FADE_MS, OPTION_ENTER_RISE_MS, OPTION_ENTER_RISE_PX, OPTION_ENTER_STAGGER_MS, type OptionOverride, type OptionOverrides, type OptionsGridLayout, type OptionsGridPlan, PLACEHOLDER_FADE_OUT_MS, PLACEHOLDER_LEAVING_ATTR, PLACEHOLDER_SWAP_GAP_MS, PLACEHOLDER_TYPE_MS, PLACEHOLDER_WORD_PAUSE_MS, PRODUCT_PATH_PREFIX, PRODUCT_ROW_PX_PER_LINE, type Product, type ProductImageFallback, type ProductRowMetrics, type ProductRowWheel, type ProductsConfig, type ProductsLayout, RANGE_SEPARATOR, type RecentlySuggested, type RenderMode, SCHEMA_VERSION, SCROLL_ARROW_ATTR, SCROLL_ARROW_BOTTOM_VAR, SCROLL_ARROW_CLASS, SCROLL_ARROW_FADE_MS, SCROLL_ARROW_LABEL, SCROLL_ARROW_SCROLL_IDLE_MS, SCROLL_ARROW_VISIBLE_ATTR, SKIPPED_PARAM_TEXT, type ScrollArrowArgs, type ScrollArrowController, type Segment, type SkippedParamState, type Store, type SubmitResultExtras, type Suggestion, type SuggestionOption, type SuggestionType, type TaskKind, WEEKDAY_LABELS, addMonths, attachProductRowWheel, attachScrollArrow, buildAttributionUrl, buildDateOptions, buildQuery, buildSubmitResult, cellDay, cellIso, chipIdFromTap, computeOptionsGridLayout, containScroll, createStore, cursorIsAtEnd, dateCellMarks, dateSelectionFor, extractPlainText, formatAbsoluteDate, formatDate, formatDateRange, formatOptionCount, getCursorOffset, getFooterHint, identifiedParamLabel, isCalendarFormat, isOptionsGridMobileViewport, isoDate, keepCaretOnChip, measureOptionsGrid, monthLabel, needsOptionsGridMeasurement, optionCountLabel, optionEnterDelayMs, optionHasImage, optionImageSrc, optionLabel, optionsEntranceDurationMs, optionsGridTemplateColumns, parseDate, parseLooseDate, parseLooseDateRange, plainTextLength, planOptionsGrid, previousGraphemeBoundary, productFromMatchedItem, productInitial, productRowWheelTarget, productsFromCustomFields, renderEditableContent, resolveFormatType, resolveIdentifiedDate, sameOptionRows, sanitizeOptionIconSvg, scrollCaretIntoView, selectedIsoFromText, selectedRangeFor, setCursorOffset, toWireIdentifiedParams, visibleDateRange, withSkippedParams };