@instruments/materialgraph 0.32.0 → 0.35.0

package/client-vocabulary.d.ts

@@ -1,6 +1,6 @@
 import type { HttpTransport } from "./http-transport.js";
 import type { ListEnumValuesOptions, ListEnumValuesResult } from "./list-enum-values-types.js";
-import type { ListAttributesOptions, ListAttributesResult, ResolveColourOptions, ResolveColourResponse } from "./types.js";
-export declare const resolveColour: (transport: HttpTransport, name: string, signal?: AbortSignal, options?: ResolveColourOptions) => Promise<ResolveColourResponse>;
+import type { ListAttributesOptions, ListAttributesResult, ResolveColorOptions, ResolveColorResponse } from "./types.js";
+export declare const resolveColor: (transport: HttpTransport, name: string, signal?: AbortSignal, options?: ResolveColorOptions) => Promise<ResolveColorResponse>;
 export declare const listAttributes: (transport: HttpTransport, options?: ListAttributesOptions, signal?: AbortSignal) => Promise<ListAttributesResult>;
 export declare const listEnumValues: (transport: HttpTransport, options?: ListEnumValuesOptions, signal?: AbortSignal) => Promise<ListEnumValuesResult>;

package/client-vocabulary.js

@@ -1,5 +1,8 @@
 import { resolveOperation } from "./operations.js";
-export const resolveColour = async (transport, name, signal, options) => await transport.requestJson(resolveOperation("resolve_colour_name"), { query: { corpusScope: options?.corpusScope, name }, signal });
+export const resolveColor = async (transport, name, signal, options) => await transport.requestJson(resolveOperation("resolve_color_name"), {
+    query: { searchCatalogueSubset: options?.searchCatalogueSubset, name },
+    signal,
+});
 /**
  * A comma list, or nothing at all for an empty one. `[].join(",")` is `""`, and
  * an absent parameter is the one honest spelling of "no restriction".

package/client.d.ts

@@ -1,14 +1,13 @@
 import type { ApplicabilityOptions, AssociatedOptions } from "./association-types.js";
 import type { BrandsOptions } from "./brand-types.js";
-import type { ByColourParams, ByColourResponse } from "./by-colour-types.js";
 import { CatalogueClient } from "./catalogue-client.js";
 import { CategoriesClient } from "./categories-client.js";
 import type { ResolvedVerdictCitation } from "./citation-types.js";
 import type { MaterialGraphClientOptions } from "./client-config.js";
-import { ColoursClient } from "./colours-client.js";
+import { ColorsClient } from "./colors-client.js";
 import type { RateLimit } from "./errors.js";
 import type { FindCompanionsInput, FindCompanionsOutput } from "./find-companions-types.js";
-import type { FindVariantsByColourInput, FindVariantsByColourOutput } from "./find-variants-by-colour-types.js";
+import type { FindVariantsByColorInput, FindVariantsByColorOutput } from "./find-variants-by-color-types.js";
 import type { FindVariantsByVectorInput, FindVariantsByVectorOutput } from "./find-variants-by-vector-types.js";
 import type { GetVariantOptions, GetVariantOutput } from "./get-variant-types.js";
 import type { VariantId } from "./identifiers.js";
@@ -16,11 +15,10 @@ import type { ListEnumValuesOptions, ListEnumValuesResult } from "./list-enum-va
 import type { ListVariantFacetsInput, ListVariantFacetsOutput } from "./list-variant-facets-types.js";
 import type { ListVariantsInput, ListVariantsOutput } from "./list-variants-types.js";
 import type { ListVariantAssetsOptions, MaterialDocumentPageOptions, VariantAssetPage } from "./material-asset-types.js";
-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 { ExtractPaletteInput, ExtractPaletteResponse, ListAttributesOptions, ListAttributesResult, PairingsOptions, PairingsResponse, ResolveColourOptions, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, WhoamiResponse } from "./types.js";
+import type { SearchVariantsInput, SearchVariantsOutput } from "./search-variants-types.js";
+import type { ExtractPaletteInput, ExtractPaletteResponse, ListAttributesOptions, ListAttributesResult, PairingsOptions, PairingsResponse, ResolveColorOptions, ResolveColorResponse, WhoamiResponse } from "./types.js";
 import { WorkflowsClient } from "./workflows-client.js";
 export * from "./client-config.js";
 /**
@@ -31,25 +29,27 @@ export * from "./client-config.js";
  *
  * | The question | The lens |
  * | --- | --- |
- * | "find me something like this / matching these words" | {@link MaterialGraphClient.search} |
+ * | "find me something matching these words" | {@link MaterialGraphClient.searchVariants} |
+ * | "find me something that looks or feels like this" | {@link MaterialGraphClient.findVariantsByVector} |
  * | "tell me about THIS variant" | {@link MaterialGraphClient.getVariant} |
  * | "which materials, from anyone, meet this hard spec?" | {@link MaterialGraphClient.listVariants} |
- * | "what's near this colour / this palette?" | {@link MaterialGraphClient.byColour}, `colours.palette()` |
- * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.listVariants} (same product, other colourways) |
- * | "what does the manufacturer say is AVAILABLE on this?" | {@link MaterialGraphClient.associatedFinishes}, {@link MaterialGraphClient.associatedProducts} |
+ * | "what's near a color, or a palette of colors?" | {@link MaterialGraphClient.findVariantsByColor} (`mode: "palette"`) |
+ * | "what colors does this category come in?" | `colors.profiles()` |
+ * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.listVariants} (same product, other colorways) |
+ * | "what does the brand say is AVAILABLE on this?" | {@link MaterialGraphClient.associatedFinishes}, {@link MaterialGraphClient.associatedProducts} |
  * | "what can I even ask for?" | {@link MaterialGraphClient.listVariantFacets}, `categories.list()` |
  * | "what is this word called here?" | {@link MaterialGraphClient.listAttributes} |
  * | "do the whole job for me, async" | `workflows.start()` + `mg:compose` |
  *
  * Three structural rules that fall out of that table:
- * - **Colour is a separate lens.** {@link MaterialGraphClient.search} matches
- *   WORDS. A colour word in `text` finds materials whose text mentions it, not
- *   materials that look it. Route visual intent to the colour lenses.
+ * - **Color is a separate lens.** {@link MaterialGraphClient.searchVariants}
+ *   matches WORDS. A color word in `query` finds materials whose text mentions
+ *   it, not materials that look it. Route visual intent to the color lenses.
  * - **Relationships hang off a material, not off a query.** You cannot ask "what
  *   pairs with beige oak"; you resolve a material first, then ask what pairs
  *   with THAT `variantId`.
  * - **Declared is not inferred.** `associatedFinishes()` /
- *   `associatedProducts()` return compatibility the MANUFACTURER stated;
+ *   `associatedProducts()` return compatibility the BRAND stated;
  *   `pairings()` returns companionship the graph INFERRED. The response shapes
  *   share no field, on purpose — render them as separate sections and never
  *   concatenate them.
@@ -62,10 +62,10 @@ export declare class MaterialGraphClient extends CatalogueClient {
     /**
      * THE QUESTION: "what kinds of thing exist, and what are their keys?"
      * `categories.list()` pages the tree (roots, one node's children, or a
-     * name/meaning search), and `categories.get(id)` reads one node in full:
+     * name search), and `categories.get(id)` reads one node in full:
      * its place, the names that find it, and the canonical taxonomy concepts it
      * relates to. The source of every category id the other lenses accept
-     * (`search({ category })`, `listVariants({ filters })`, `colours.profiles()`).
+     * (`listVariants({ filters })`, `findVariantsByColor({ categoryIds })`).
      *
      * A category id is a TREE KEY, never a canonical `product_category` value:
      * the two look alike and are not interchangeable. Discover ids here, never
@@ -74,17 +74,19 @@ export declare class MaterialGraphClient extends CatalogueClient {
      */
     readonly categories: CategoriesClient;
     /**
-     * THE QUESTION: "what colours exist here?" and "what matches this whole SET
-     * of colours?" (`palette`).
+     * THE QUESTION: "what colors does this category come in?" (`profiles`).
+     * `profiles` is an aggregate over a category, not a list of materials, and
+     * carries a `basis` naming the snapshot it read.
      *
-     * Instead use {@link MaterialGraphClient.byColour} for ONE colour and
-     * {@link MaterialGraphClient.listVariants} to page through a colour's family.
-     * Colour is usually derived from product imagery, which is visual likeness,
-     * not a colour specification. A brand's declared colour, such as a paint's
+     * Instead use {@link MaterialGraphClient.findVariantsByColor} (`mode:
+     * "palette"`) for the materials near one or several colors and
+     * {@link MaterialGraphClient.listVariants} to page through a color's family.
+     * Color is usually derived from product imagery, which is visual likeness,
+     * not a color specification. A brand's declared color, such as a paint's
      * published hex, wins where MaterialGraph holds one, and each value's
-     * source basis says which.
+     * value origin says which.
      */
-    readonly colours: ColoursClient;
+    readonly colors: ColorsClient;
     /**
      * THE QUESTION: "do a whole job for me" — the ASYNC lens. `start()` begins a
      * Run of one registered workflow, `run()` polls it, `streamRunEvents()` and
@@ -95,51 +97,6 @@ export declare class MaterialGraphClient extends CatalogueClient {
     readonly workflows: WorkflowsClient;
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
-    /**
-     * THE QUESTION: "find me materials like this": one search over the words, or
-     * a seed or query image, optionally gated by a category, hard attribute
-     * filters and a corpus scope (ADR 0031).
-     *
-     * Instead use {@link MaterialGraphClient.listVariants} when the spec IS the question
-     * (ranking would be noise), {@link MaterialGraphClient.byColour} /
-     * `colours.palette()` for visual colour intent (`text` matches WORDS — "sage
-     * green" finds materials that SAY sage, not ones that look it),
-     * {@link MaterialGraphClient.pairings}
-     * for what goes WITH something, {@link MaterialGraphClient.suggest} for typeahead.
-     *
-     * The full POST search primitive. `input.filters` are hard token sets on
-     * the search index, run in the same query; they change no ordering. Build
-     * them with `certificationProgramme`, `specTerm`, or `hasSpec`. Weights,
-     * mood, colours, sort and preferences are gone, and the server refuses them
-     * by name.
-     */
-    search(input: SearchInput & CardProjectionRequest, signal?: AbortSignal): Promise<SearchCardResponse>;
-    search(input: SearchInput, signal?: AbortSignal): Promise<SearchResponse>;
-    /** Whole materials ask → inspectable meanings and complete safe search requests. */
-    planQuery(query: string, signal?: AbortSignal): Promise<MaterialQueryPlan>;
-    /**
-     * The same question as {@link MaterialGraphClient.search}; the difference is
-     * transport: a cacheable, link-shareable GET for queries that must survive in
-     * a URL. `category`, `filters` and image bytes have no query-string form, so
-     * anything using those must go through `search`.
-     */
-    searchGet(params: SearchGetParams & {
-        view: "card";
-    }, signal?: AbortSignal): Promise<SearchCardResponse>;
-    searchGet(params: SearchGetParams, signal?: AbortSignal): Promise<SearchResponse>;
-    /**
-     * THE QUESTION: "what materials are near THIS colour?" — one colour (or a small
-     * palette), ranked by OKLab closeness to colour extracted from product imagery.
-     *
-     * Instead use `colours.palette()` for N colours at stated proportions (a
-     * different ranking, not a wrapper),
-     * {@link MaterialGraphClient.resolveColour} first if you hold a NAME,
-     * {@link MaterialGraphClient.listVariants} to page through a category or a brand, and
-     * {@link MaterialGraphClient.search} when colour is one signal among many.
-     * Report matches as visual likeness, never a stated colour specification.
-     * `family` gates to ONE colorscope family (a gated page can be short); `brand` gates to named brands — one brand's nearest colour to another's.
-     */
-    byColour(params: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
     /**
      * THE QUESTION: "tell me about THIS variant" (GET
      * `/api/v1/variants/{variantId}`, `get_variant`).
@@ -150,10 +107,10 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * product, brand, category, image and page. Name `attributes` and `blocks`
      * to add their values under `specifications`; a null value is unknown, never
      * false or zero. Instead use {@link MaterialGraphClient.listVariants} for many
-     * ids, or for the other colourways of the same product (ask `listVariants`
+     * ids, or for the other colorways of the same product (ask `listVariants`
      * with a `product in` filter),
      * {@link MaterialGraphClient.materialBlocks} to tell "no value" from "not
-     * checked", {@link MaterialGraphClient.search} when you have no id yet.
+     * checked", {@link MaterialGraphClient.searchVariants} when you have no id yet.
      *
      * @param variantId Opaque — pass back exactly what you were given.
      */
@@ -173,37 +130,39 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * off one resolved material (GET `/api/v1/materials/{variantId}/pairings`).
      *
      * Instead use {@link MaterialGraphClient.listVariants} for the same product in
-     * another colour, and `search({ similarTo })` for a LIKE-THIS substitute —
+     * another color, and {@link MaterialGraphClient.findVariantsByVector} for a LIKE-THIS substitute —
      * similar and complementary are opposite questions.
      *
      * READ `item.source` BEFORE PHRASING: the rail mixes three tiers of evidence —
-     * `cospec` (real orders), `considered` (board activity), `colour` (palette
+     * `cospec` (real orders), `considered` (board activity), `color` (palette
      * look-alike). Only `cospec` supports "sampled together". `cospecCount` tells
      * you how much of the rail is real order evidence.
      */
     pairings(variantId: VariantId, options?: PairingsOptions, signal?: AbortSignal): Promise<PairingsResponse>;
-    /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
+    /** "What finishes does the brand declare for THIS product?" - {@link declaredFinishes}. */
     associatedFinishes(variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<import("./association-types.js").DeclaredAssociationsResponse>;
-    /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
+    /** "What products does the brand declare THIS finish for?" - {@link declaredProducts}. */
     associatedProducts(variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<import("./association-types.js").DeclaredAssociationsResponse>;
     applicability(options: ApplicabilityOptions, signal?: AbortSignal): Promise<import("./association-types.js").ApplicabilityResponse>;
     /**
      * THE QUESTION: "eligible variants matching these hard filters, ranked and
      * cursor-paged" (GET `/api/v1/variants`, MG-2222) — the one read behind
      * `list_variants`, hydrating ids you already hold (`{terms: [{field:
-     * "variant", op: "in", values: [...]}]}`, up to 100), the other colourways
+     * "variant", op: "in", values: [...]}]}`, up to 100), the other colorways
      * of a product (`{terms: [{field: "product", op: "in", values:
      * [productId]}, {field: "variant", op: "not_in", values: [variantId]}]}` —
-     * `filters` is kind-grouped, `{terms, numbers, presence}`, every condition
-     * across all three ANDed), or a category/brand listing. An explicit
+     * `filters` is kind-grouped, `{terms, numbers, presence, anyField}`, every
+     * condition across all four ANDed, 20 at most), or a category/brand listing. An explicit
      * `variant in` id that does not resolve to an eligible variant is
-     * reported in `unresolvedVariantIds`, or in `excludedByCorpusScope` when
-     * it names a real variant outside the materials catalogue, never silently
-     * dropped from the page.
+     * reported in `unresolvedVariantIds` when it names no variant, in
+     * `unavailableVariantIds` when it names a catalogue variant this list
+     * cannot show in the requested scope (a retired one, for example), or in
+     * `excludedBySearchCatalogueSubset` when 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`/`colors` 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>;
     /**
@@ -211,27 +170,41 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * and how many of each" (POST `/api/v1/variants/facets`, MG-2294) — the
      * options and counts a filter UI shows beside a {@link
      * MaterialGraphClient.listVariants} page. `filters` is the same tree
-     * `listVariants()` takes; the server validates both.
+     * `listVariants()` takes, less its `orText` and `unstated` additions; 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).
-     * One required `mode`: `contains` (a swatch for every required `colours[]`
-     * condition), `palette` (whole-palette closeness to `colours[]`, an
+     * color?" (POST `/api/v1/variants/by-color`, MG-2217/MG-2230/MG-2247).
+     * One required `mode`: `contains` (a swatch for every required `colors[]`
+     * condition), `palette` (whole-palette closeness to `colors[]`, an
      * image's extracted palette, or `targetVariantId`'s own palette) or
-     * `rerank` (reorder a held `variantIds` set by colour closeness). Use
-     * {@link MaterialGraphClient.byColour} instead for ONE colour against the
-     * search index rather than the canonical variant graph.
+     * `rerank` (reorder a held `variantIds` set by color closeness).
      */
-    findVariantsByColour(input: FindVariantsByColourInput, signal?: AbortSignal): Promise<FindVariantsByColourOutput>;
+    findVariantsByColor(input: FindVariantsByColorInput, signal?: AbortSignal): Promise<FindVariantsByColorOutput>;
     /**
      * THE QUESTION: "what did designers sample together with these?" (POST
      * `/api/v1/variants/companions`, MG-2332). Give `variantIds` and/or
      * `materials` (free-text names, one variant each, at most twelve together);
      * companions come back strongest first, each with its `lift`,
      * `seedMatchCount`, `relation` and a one-line `reason`. `projectType` reads one
-     * sector; `include` adds `image` and `colour` fields a lean page leaves out.
+     * sector; `include` adds `image` and `color` fields a lean page leaves out.
      * A sample order shows sampling, never specification. Read `unresolved`
      * before presenting: a scheme of four that resolved two is a different claim.
      */
@@ -241,13 +214,14 @@ export declare class MaterialGraphClient extends CatalogueClient {
      * `/api/v1/variants/by-vector`, MG-2231). Eligible variants ranked by
      * semantic or visual similarity to a text description (mood words count),
      * an image reference, or both fused into one embedding. `filters` is the
-     * same tree {@link MaterialGraphClient.listVariants} takes. `query.mode`
+     * same tree {@link MaterialGraphClient.listVariants} takes, less its `orText`
+     * and `unstated` additions. `query.mode`
      * values other than `"text"` embed through Voyage and spend the shared
      * per-key `embed` rate budget.
      */
     findVariantsByVector(input: FindVariantsByVectorInput, signal?: AbortSignal): Promise<FindVariantsByVectorOutput>;
-    /** Resolve a colour name to its hex, and the named paint's catalogue variant. */
-    resolveColour(name: string, signal?: AbortSignal, options?: ResolveColourOptions): Promise<ResolveColourResponse>;
+    /** Resolve a color name to its hex, and the named paint's catalogue variant. */
+    resolveColor(name: string, signal?: AbortSignal, options?: ResolveColorOptions): Promise<ResolveColorResponse>;
     /**
      * THE QUESTION: "which attribute means this phrase?" or "what could a
      * <category> be specified by?" (GET `/api/v1/catalog/attributes`). One page of
@@ -276,15 +250,14 @@ export declare class MaterialGraphClient extends CatalogueClient {
      */
     whoami(signal?: AbortSignal): Promise<WhoamiResponse>;
     /**
-     * THE QUESTION: "what colours are in this image?" — the palette only, no
-     * materials. The bridge from an inspiration image into the colour lens: extract
-     * here, then feed the swatches to `colours.palette()` or
-     * {@link MaterialGraphClient.byColour}. Instead use
-  
+     * THE QUESTION: "what colors are in this image?" — the palette only, no
+     * materials. The bridge from an inspiration image into the color lens: extract
+     * here, then feed the swatches to
+     * {@link MaterialGraphClient.findVariantsByColor} (`mode: "palette"`).
      */
     extractPalette(input: ExtractPaletteInput, signal?: AbortSignal): Promise<ExtractPaletteResponse>;
     /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
-    brands(options?: BrandsOptions, signal?: AbortSignal): Promise<import("./brand-types.js").BrandCatalogListPage>;
+    brands(options?: BrandsOptions, signal?: AbortSignal): Promise<import("./brand-types.js").ListBrandsPage>;
     /**
      * Upload one atomic source-material batch (POST `/api/v1/source-material`,
      * multipart). Pass a heterogeneous pile via `{ files }` (any mix of PDF,