@instruments/materialgraph 0.32.0 → 0.33.0

package/by-spec-types.d.ts

@@ -56,9 +56,8 @@ export type BySpecVerdictCell = {
      * Why an `unverified` cell missed the bar; null otherwise.
      *  - `below_confidence` — the value is real but scored under the floor.
      *  - `basis_unmet` — the value's source is weaker than the criterion demanded.
-     *  - `proposed` — the value is awaiting acceptance and is not yet on record.
      */
-    trustGap: "below_confidence" | "basis_unmet" | "proposed" | null;
+    trustGap: "below_confidence" | "basis_unmet" | null;
     citation?: VerdictCitation;
 };
 /**

package/client.d.ts

@@ -20,6 +20,7 @@ import type { MaterialQueryPlan } from "./material-query-plan-types.js";
 import type { SourceMaterialBatchReceipt, UploadSourceMaterialInput } from "./run-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
 import type { CardProjectionRequest, SearchCardResponse } from "./search-card-types.js";
+import type { SearchVariantsInput, SearchVariantsOutput } from "./search-variants-types.js";
 import type { ExtractPaletteInput, ExtractPaletteResponse, ListAttributesOptions, ListAttributesResult, PairingsOptions, PairingsResponse, ResolveColourOptions, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, WhoamiResponse } from "./types.js";
 import { WorkflowsClient } from "./workflows-client.js";
 export * from "./client-config.js";
@@ -201,9 +202,9 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * it names a real variant outside the materials catalogue, never silently
      * dropped from the page.
      *
-     * `filters`/`optionalFilters`/`orderBy` are sent as URL-encoded JSON;
-     * `attributes`/`include` as comma-separated lists — the server validates,
-     * this method does not duplicate that check.
+     * `filters`/`optionalFilters`/`orderBy`/`colours` are sent as URL-encoded
+     * JSON; `attributes`/`include`/`words` as comma-separated lists — the server
+     * validates, this method does not duplicate that check.
      */
     listVariants(input: ListVariantsInput, signal?: AbortSignal): Promise<ListVariantsOutput>;
     /**
@@ -214,6 +215,21 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * `listVariants()` takes; the server validates both.
      */
     listVariantFacets(input: ListVariantFacetsInput, signal?: AbortSignal): Promise<ListVariantFacetsOutput>;
+    /**
+     * THE QUESTION: "which variants match these plain words, and how did you
+     * read them?" (POST `/api/v1/variants/search`, MG-2223) — `query` is read
+     * into the filters {@link MaterialGraphClient.listVariants} takes, run
+     * through it, and answered with `understood` (what each phrase became, or
+     * why it did nothing) beside the page. `filters`, `optionalFilters` and
+     * `name` are exactly what ran, so the three can be sent to `listVariants()`
+     * to narrow or widen the same search; page with this method's own cursor,
+     * which `listVariants()` refuses. A phrase with several meanings is
+     * answered with one and listed in `choices`; send its `handle` with an
+     * alternative's `group` and `id` in `selections` to switch it. A query that
+     * applies nothing returns no items, never the whole catalogue; a preference
+     * alone still ranks it.
+     */
+    searchVariants(input: SearchVariantsInput, signal?: AbortSignal): Promise<SearchVariantsOutput>;
     /**
      * THE QUESTION: "which variants hold, resemble, or can be ranked by, this
      * colour?" (POST `/api/v1/variants/by-colour`, MG-2217/MG-2230/MG-2247).

package/client.js

@@ -250,9 +250,9 @@ export class MaterialGraphClient extends CatalogueClient {
      * it names a real variant outside the materials catalogue, never silently
      * dropped from the page.
      *
-     * `filters`/`optionalFilters`/`orderBy` are sent as URL-encoded JSON;
-     * `attributes`/`include` as comma-separated lists — the server validates,
-     * this method does not duplicate that check.
+     * `filters`/`optionalFilters`/`orderBy`/`colours` are sent as URL-encoded
+     * JSON; `attributes`/`include`/`words` as comma-separated lists — the server
+     * validates, this method does not duplicate that check.
      */
     async listVariants(input, signal) {
         return await this.#get("list_variants", {
@@ -260,6 +260,9 @@ export class MaterialGraphClient extends CatalogueClient {
                 ? input.attributes.join(",")
                 : undefined,
             collapse: input.collapse,
+            colours: input.colours?.length
+                ? JSON.stringify(input.colours)
+                : undefined,
             corpusScope: input.corpusScope,
             cursor: input.cursor,
             filters: input.filters ? JSON.stringify(input.filters) : undefined,
@@ -272,6 +275,7 @@ export class MaterialGraphClient extends CatalogueClient {
             orderBy: input.orderBy?.length
                 ? JSON.stringify(input.orderBy)
                 : undefined,
+            words: input.words?.length ? input.words.join(",") : undefined,
         }, signal);
     }
     /**
@@ -284,6 +288,23 @@ export class MaterialGraphClient extends CatalogueClient {
     async listVariantFacets(input, signal) {
         return await this.#post("list_variant_facets", input, signal);
     }
+    /**
+     * THE QUESTION: "which variants match these plain words, and how did you
+     * read them?" (POST `/api/v1/variants/search`, MG-2223) — `query` is read
+     * into the filters {@link MaterialGraphClient.listVariants} takes, run
+     * through it, and answered with `understood` (what each phrase became, or
+     * why it did nothing) beside the page. `filters`, `optionalFilters` and
+     * `name` are exactly what ran, so the three can be sent to `listVariants()`
+     * to narrow or widen the same search; page with this method's own cursor,
+     * which `listVariants()` refuses. A phrase with several meanings is
+     * answered with one and listed in `choices`; send its `handle` with an
+     * alternative's `group` and `id` in `selections` to switch it. A query that
+     * applies nothing returns no items, never the whole catalogue; a preference
+     * alone still ranks it.
+     */
+    async searchVariants(input, signal) {
+        return await this.#post("search_variants", input, signal);
+    }
     /**
      * THE QUESTION: "which variants hold, resemble, or can be ranked by, this
      * colour?" (POST `/api/v1/variants/by-colour`, MG-2217/MG-2230/MG-2247).

package/index.d.ts

@@ -2,6 +2,7 @@ export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
 export type { MaterialGraphClientOptions } from "./client.js";
 export type * from "./list-variants-types.js";
 export type * from "./list-variant-facets-types.js";
+export type * from "./search-variants-types.js";
 export type * from "./list-enum-values-types.js";
 export type * from "./get-variant-types.js";
 export type * from "./image-reference-types.js";

package/list-variants-types.d.ts

@@ -26,20 +26,33 @@ export type FilterPresenceCondition = {
     op: "exists" | "missing";
 };
 /**
- * One filter condition, whichever of the three fully-required shapes. No
+ * A term stated under ANY of `fields` (2–8 distinct term attributes), for a
+ * concept stored under several of them. `in`: at least one of `values` under
+ * at least one field. `not_in`: at least one field stated at all, and none of
+ * `values` under any field.
+ */
+export type FilterAnyFieldCondition = {
+    fields: string[];
+    op: "in" | "not_in";
+    values: string[];
+};
+/**
+ * One filter condition, whichever of the four fully-required shapes. No
  * `unit` key (a numeric value is in the attribute's own canonical unit).
  */
-export type FilterCondition = FilterTermCondition | FilterNumericCondition | FilterPresenceCondition;
+export type FilterCondition = FilterTermCondition | FilterNumericCondition | FilterPresenceCondition | FilterAnyFieldCondition;
 /**
  * `filters`: kind-grouped, not a flat list (MG-2222) — `{terms, numbers,
- * presence}`. Every condition across all three arrays must match (AND); OR
- * within one field is `in`. Send only the arrays you need; an omitted or
- * empty array carries no conditions.
+ * presence, anyField}`. Every condition across all four arrays must match
+ * (AND); OR within one field is `in`, and `anyField` is OR across several
+ * fields. Send only the arrays you need; an omitted or empty array carries no
+ * conditions.
  */
 export type FilterGroups = {
     terms?: FilterTermCondition[];
     numbers?: FilterNumericCondition[];
     presence?: FilterPresenceCondition[];
+    anyField?: FilterAnyFieldCondition[];
 };
 /** `optionalFilters`: the same kind-grouped shape as `filters`, with every entry also carrying a required `weight` (1–10). Ranks matched items; never excludes. */
 export type OptionalFilterGroups = {
@@ -52,6 +65,9 @@ export type OptionalFilterGroups = {
     presence?: (FilterPresenceCondition & {
         weight: number;
     })[];
+    anyField?: (FilterAnyFieldCondition & {
+        weight: number;
+    })[];
 };
 export type OrderByEntry = {
     direction: "asc" | "desc";
@@ -59,23 +75,44 @@ export type OrderByEntry = {
     field: string;
 };
 export type ListVariantsInclude = "image" | "url";
-export type ListVariantsCollapse = "product";
+export type ListVariantsCollapse = "product" | "colourway";
+/** A region in OKLCh: lightness and chroma as bounds, hue an arc in degrees that wraps when its start is past its end, null for any hue. */
+export type ColourRegion = {
+    chroma: [number, number];
+    hue: [number, number] | null;
+    lightness: [number, number];
+};
+/**
+ * A measured-colour condition. `in` keeps a variant with a large swatch inside
+ * `range`; `not_in` leaves those out and lets a variant with no measured
+ * colour pass. `preferred` only orders and never narrows.
+ */
+export type ColourRangeCondition = {
+    /** The colour's own point in the region, `#rrggbb`; it orders matches, nearest first. */
+    hex: string;
+    intent?: "required" | "preferred";
+    op: "in" | "not_in";
+    range: ColourRegion;
+};
 export type ListVariantsInput = {
     /** Attribute ids to project under each item's `specifications`. */
     attributes?: string[];
     /**
      * `product`: one row per product, its lead colourway by the page's order,
      * with `variantCount` saying how many colourways stand behind it. The
-     * cursor pages products.
+     * cursor pages products. `colourway`: one row per colourway, so a colour
+     * sold on several substrates is one row.
      */
     collapse?: ListVariantsCollapse;
+    /** Up to four measured-colour regions. */
+    colours?: ColourRangeCondition[];
     /**
      * Only variants in this corpus scope: the rows, the page and the cursor.
      * Absent or `all` is every variant.
      */
     corpusScope?: CorpusScope;
     cursor?: string;
-    /** Every condition, across `terms`/`numbers`/`presence`, must match. */
+    /** Every condition, across `terms`/`numbers`/`presence`/`anyField`, must match. */
     filters?: FilterGroups;
     include?: ListVariantsInclude[];
     /** 1–50; defaults to 10. */
@@ -89,10 +126,12 @@ export type ListVariantsInput = {
     /** Rank only — never excludes. */
     optionalFilters?: OptionalFilterGroups;
     orderBy?: OrderByEntry[];
+    /** Words each variant must name in its text, inside the filters. */
+    words?: string[];
 };
 /**
  * `score` sums the weights of the matched `optionalFilters`; `matched` lists
- * their positions in the flattened terms-then-numbers-then-presence order
+ * their positions in the flattened terms-then-numbers-then-presence-then-anyField order
  * the server reads `optionalFilters` in, not the caller's own array shape.
  */
 export type ListVariantsPreference = {

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["samplizeColorVecCache", "GET", "/api/v1/catalogues/samplize/colorvec", "samplize_colorvec_cache"], readonly ["samplizeCatalogueSearch", "POST", "/api/v1/catalogues/samplize/search", "samplize_catalogue_search"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], readonly ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["findVariantsByColour", "POST", "/api/v1/variants/by-colour", "find_variants_by_colour"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findCompanions", "POST", "/api/v1/variants/companions", "find_companions"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["workflows.start", "POST", "/api/v1/workflows/{workflowId}/runs", "create_public_run"], readonly ["workflows.run", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}", "get_public_run"], readonly ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["samplizeColorVecCache", "GET", "/api/v1/catalogues/samplize/colorvec", "samplize_colorvec_cache"], readonly ["samplizeCatalogueSearch", "POST", "/api/v1/catalogues/samplize/search", "samplize_catalogue_search"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], readonly ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColour", "POST", "/api/v1/variants/by-colour", "find_variants_by_colour"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findCompanions", "POST", "/api/v1/variants/companions", "find_companions"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["workflows.start", "POST", "/api/v1/workflows/{workflowId}/runs", "create_public_run"], readonly ["workflows.run", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}", "get_public_run"], readonly ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -110,6 +110,7 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/variants/facets",
         "list_variant_facets",
     ],
+    ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"],
     [
         "findVariantsByColour",
         "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "type": "module",
   "exports": {
     ".": {

package/response-schemas.generated.d.ts

@@ -1,5 +1,5 @@
 /** The API contract version the schemas were generated from. */
 export declare const RESPONSE_SCHEMA_API_VERSION = "0.7.0";
 /** Every SDK operation whose success response has a published JSON Schema. */
-export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["samplize_colorvec_cache", "samplize_catalogue_search", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "search_materials_post", "plan_material_query", "samplize_catalogue_products", "search_materials_get", "search_by_colour", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "find_variants_by_colour", "find_variants_by_vector", "find_companions", "resolve_variant", "get_variant", "resolve_colour_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "search_by_palette", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run", "get_verdict_citation"];
+export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["samplize_colorvec_cache", "samplize_catalogue_search", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "search_materials_post", "plan_material_query", "samplize_catalogue_products", "search_materials_get", "search_by_colour", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_colour", "find_variants_by_vector", "find_companions", "resolve_variant", "get_variant", "resolve_colour_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "search_by_palette", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run", "get_verdict_citation"];
 export declare const RESPONSE_SCHEMA_CATALOGUE_JSON: string;