@instruments/materialgraph 0.28.0 → 0.30.0

package/colours-client.js

@@ -3,80 +3,11 @@ export class ColoursClient {
     constructor(transport) {
         this.#transport = transport;
     }
-    /**
-     * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
-     * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).
-     *
-     * An aggregate over a category, not a list of materials: use `mg.byColour()` or
-     * `mg.search()` when you want the materials themselves, and
-     * {@link ColoursClient.stats} for coverage across the whole corpus rather than
-     * one category's palette. Check `basis` — this reads a scheduled materialized
-     * view, so it can lag the catalog.
-     *
-     * `groupBy: "group"` takes product-type GROUP keys and merges every leaf type
-     * under a group into one histogram BEFORE ranking — a group's palette, not the
-     * union of its leaves' heads. `select: "diverse"` returns visually spread
-     * swatches (greedy max-min over OKLab, 0.02 minimum separation, backfilled by
-     * frequency if fewer survive) instead of the most frequent ones; a client
-     * cannot recover that spread from a truncated frequency list, which is why it
-     * is a server mode rather than a local sort.
-     *
-     * `groupBy: "merged"` merges across the KEYS as well and returns ONE profile
-     * over the union of their leaves — the palette of a caller-defined facet such
-     * as "Wood" (`wood_surface` + `wood_flooring`) that the taxonomy holds no
-     * single node for, and that no combination of per-key responses reconstructs.
-     * Its keys may sit at either tier, `categoryKey` is those keys sorted and
-     * joined with `+`, and `members` hands them back so nothing has to split it.
-     *
-     * A selected category with no colour data comes back as a zero-count profile,
-     * not a missing key.
-     */
-    async profiles(params, signal) {
-        return await this.#transport.get("get_category_colour_profiles", {
-            groupBy: params.groupBy,
-            productTypeIds: params.productTypeIds.join(","),
-            select: params.select,
-            topN: params.topN,
-        }, signal);
-    }
-    /**
-     * THE QUESTION: "how much colour does the graph hold AT ALL?" — corpus-level
-     * coverage, before you trust any colour answer.
-     *
-     * The sanity check under every other colour call. Use
-     * {@link ColoursClient.profiles} for one category's palette and
-     * `mg.colourFacets()` for the vocabulary. `basis.omissions` lists what this
-     * call deliberately does not answer — read it rather than assuming silence.
-     *
-     * Corpus colour coverage (GET `/api/v1/colours/stats`): how much of the graph
-     * carries colour at all, the split across the canonical colour families, and
-     * coverage per product-type group. `basis` states the source and freshness of
-     * each section plus `basis.omissions` — what this call deliberately does not
-     * answer, listed rather than silently absent.
-     *
-     * Pass `{ groupBy: "brand,category" }` for the whole brand x category x
-     * family matrix in one call, or a `brandSlug`/`categoryKey` scope for a slice
-     * of it — either way it arrives as `rows`, each row carrying `brandId` and
-     * `brandSlug` to join on. Without any of those parameters the payload is the
-     * platform-wide one and `rows` is absent. `families` is never scoped by them.
-     */
-    async stats(params = {}, signal) {
-        return await this.#transport.get("get_colour_stats", {
-            brandId: params.brandId,
-            brandSlug: params.brandSlug,
-            categoryKey: params.categoryKey,
-            family: params.family,
-            groupBy: params.groupBy,
-            limit: params.limit,
-        }, signal);
-    }
     /**
      * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at
      * stated proportions, not one colour repeated (POST `/api/v1/search/palettes`).
      *
-     * Use `mg.byColour()` for a single colour, {@link ColoursClient.gradient} when
-     * the colours form an ordered TRANSITION rather than a set, and
-     * `mg.coordinate()` when the scheme is made of materials rather than colours.
+     * Use `mg.byColour()` for a single colour.
      *
      * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
      * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
@@ -104,19 +35,4 @@ export class ColoursClient {
     async palette(input, signal) {
         return await this.#transport.post("search_by_palette", input, signal);
     }
-    /**
-     * THE QUESTION: "what moves from this colour to that one?" — materials that
-     * travel ALONG a transition, in order (POST `/api/v1/search/gradients`).
-     *
-     * Order is the whole point: use {@link ColoursClient.palette} when the colours
-     * are a set rather than a path, and `mg.byColour()` for a single colour.
-     *
-     * Not a palette: the score is multiplied by `coverage`, the share of the path
-     * the candidate actually spans, so a material owning only one end ranks below
-     * one that travels the whole way, and a flat single-colour material is
-     * rejected outright however close its hue sits to the path.
-     */
-    async gradient(input, signal) {
-        return await this.#transport.post("search_by_gradient", input, signal);
-    }
 }

package/find-variants-by-colour-types.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @module find-variants-by-colour-types
+ * @description Hand-maintained mirror of `find_variants_by_colour`'s
+ * (MG-2217/MG-2230/MG-2247/MG-2328) input and output wire shapes. The source
+ * of truth is `packages/products/src/search/find-variants-by-colour.ts` —
+ * `rerank`'s `reference.candidates`/`reference.seed` still mirror
+ * `compare-colour-similarity.ts`'s own seed shape, but its `matches[]` card
+ * is the same shape CONTAINS/PALETTE use, not a copy of that module's result.
+ * This SDK has no RUNTIME dependency on `@materialgraph/products` (it's a
+ * devDependency only, for the parity tests in `__tests__/`), so the shapes
+ * are copied here rather than imported. `contract-parity.test.ts` keeps this
+ * mirror honest against the server types.
+ */
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
+import type { ImageReferenceInput } from "./image-reference-types.js";
+export type FindVariantsByColourMode = "contains" | "palette" | "rerank";
+/** One colour condition. `role` defaults to `required`; every other field defaults to absent/false/0. */
+export type ColourConditionInput = {
+    /** Name, code or hex (e.g. "sage green"). */
+    colour?: string;
+    /** Must be the swatch's largest colour. */
+    dominant?: boolean;
+    role?: "required" | "preferred";
+    /** Target (palette) or minimum (contains) share. */
+    share?: number;
+    /** Maximum share, e.g. an accent. */
+    shareMax?: number;
+};
+export type FindVariantsByColourInput = {
+    /** Brand slugs or names to filter to. */
+    brands?: string[];
+    /** One entry per colour (exactly one for rerank). */
+    colours?: ColourConditionInput[];
+    corpusScope?: CorpusScope;
+    cursor?: string;
+    /** Palette only: targets from this image's colours, not `colours[]`. */
+    image?: ImageReferenceInput;
+    limit?: number;
+    mode: FindVariantsByColourMode;
+    /** Category keys, e.g. wallcovering, floor_tile, upholstery. */
+    productTypeIds?: string[];
+    /** palette: match its palette. rerank: rank by its colour. */
+    targetVariantId?: string;
+    /** Ids to reorder by colour (rerank). */
+    variantIds?: string[];
+};
+export type ColourConditionReceipt = {
+    /** OKLab distance to the matched swatch. Never a probability. */
+    distance: number;
+    hex: string;
+    /** Position in the request's `colours[]`. */
+    index: number;
+    /** The matched swatch's share of its image, 0 to 1. */
+    proportion: number;
+    /** Requested target share, palette only; null otherwise. Ranked by, not filtered. */
+    target: number | null;
+};
+export type PaintCatalogVariant = {
+    brand: string;
+    color: string | null;
+    imageUrl: string | null;
+    product: string;
+    variantId: string;
+    variantName: string | null;
+};
+export type ResolvedColour = {
+    catalogueVariant: PaintCatalogVariant | null;
+    hex: string;
+    index: number;
+    /** `region`: a named meaning's own OKLCh bounds, kept — never collapsed to one hex. */
+    kind: "point" | "region";
+    /** Renormalised share, image-extracted colours only; else null. */
+    share: number | null;
+};
+export type ColourAlternative = {
+    code?: string;
+    hex: string;
+    libraryId: string;
+    libraryName: string;
+    name: string;
+    query: string;
+};
+export type UnresolvedColour = {
+    alternatives: ColourAlternative[];
+    index: number;
+    input: string | null;
+};
+export type ColourVariantMatch = {
+    brand: string;
+    brandId: string;
+    category: string;
+    code: string | null;
+    colours: ColourConditionReceipt[];
+    /** Share of the request's colours this variant matched, 0 to 1. Never a probability. */
+    coverage: number;
+    imageUrl: string | null;
+    product: string;
+    productId: string;
+    variantId: string;
+    variantName: string;
+};
+export type ColourPageInfo = {
+    endCursor: string | null;
+    hasNextPage: boolean;
+    /**
+     * True when matches exist that the ranked pool never checked, so a
+     * narrower scope would surface them; the page may under-report, never
+     * over-report. `contains`: set on every page once the gated set outgrew
+     * its ColorVec ordering, and always when unscoped. `palette`: set only on
+     * the page where paging stops at the pool's 400 cap.
+     */
+    poolTruncated: boolean;
+};
+type ContainsOrPaletteResult = {
+    /** Colour-matched candidates dropped by `list_variants`' hard filters or eligibility. */
+    gatedOut: number;
+    matches: ColourVariantMatch[];
+    pageInfo: ColourPageInfo;
+    resolvedColours: ResolvedColour[];
+    unresolvedColours: UnresolvedColour[];
+};
+export type FindVariantsByColourContainsResult = ContainsOrPaletteResult & {
+    mode: "contains";
+};
+export type FindVariantsByColourPaletteResult = ContainsOrPaletteResult & {
+    mode: "palette";
+};
+/** `reference.candidates`/`reference.seed`'s shape — mirrors `compare-colour-similarity.ts`'s own seed, unlike `matches[]` below. */
+export type ColourRankedSeed = {
+    brand: string;
+    brandSlug: string;
+    color: string | null;
+    imageUrl: string | null;
+    product: string;
+    productId: string;
+    variantId: string;
+    /** The variant's own name — paint colourway names live here (label contract). */
+    variantName: string | null;
+};
+/** RERANK's own card — the same shape `ColourVariantMatch` above (`brandId`, `code`), plus its two ranking-only fields. */
+export type ColourRankMatch = {
+    brand: string;
+    brandId: string;
+    code: string | null;
+    /** Colour similarity in [0,1], 1 = identical palette; null when unembedded. */
+    colourSimilarity: number | null;
+    /** Cosine distance computed in TypeScript (0 = identical); null when unembedded. */
+    distance: number | null;
+    imageUrl: string | null;
+    product: string;
+    productId: string;
+    variantId: string;
+    variantName: string | null;
+};
+export type ResolvedColourReference = {
+    hex: string;
+    name: string | null;
+    ref: string;
+};
+export type CompareColourSimilarityReference = {
+    /** Best-per-brand candidates when `resolution === "ambiguous"`; empty otherwise. */
+    candidates: ColourRankedSeed[];
+    /** The resolved colour when the reference was a `colour`, else null. */
+    colour: ResolvedColourReference | null;
+    /** The input as given, so an agent can react to a miss. */
+    input: {
+        colour?: string;
+        material?: string;
+        oklab?: {
+            L: number;
+            a: number;
+            b: number;
+        };
+        variantId?: string;
+    };
+    /** `ambiguous` when a colour-name material reference spans several brands. */
+    resolution: "resolved" | "ambiguous";
+    /** The resolved seed when the reference was a `material`/`variantId`, else null. */
+    seed: ColourRankedSeed | null;
+};
+export type FindVariantsByColourRerankResult = {
+    /** Present ONLY when the request narrowed it. ABSENT means the whole graph. */
+    corpusScope?: CorpusScopeReceipt;
+    /** Real variant ids outside `corpusScope` or the materials catalogue. Present when a scope narrowed or any was excluded. */
+    excludedByCorpusScope?: string[];
+    /** Candidates ranked by ascending colour distance; unembedded ones last. */
+    matches: ColourRankMatch[];
+    mode: "rerank";
+    /** The reference, echoed with its resolution. */
+    reference: CompareColourSimilarityReference;
+    /** The reference colour, echoed in the same shape CONTAINS/PALETTE use — always 0 or 1 entries. */
+    resolvedColours: ResolvedColour[];
+    /** Candidate ids that did not resolve to any variant. */
+    unresolved: string[];
+};
+export type FindVariantsByColourOutput = FindVariantsByColourContainsResult | FindVariantsByColourPaletteResult | FindVariantsByColourRerankResult;
+export {};

package/find-variants-by-vector-types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @module find-variants-by-vector-types
+ * @description Hand-maintained mirror of `find_variants_by_vector`'s
+ * (MG-2231) input and output wire shapes. The source of truth is
+ * `packages/products/src/vector-discovery/find-variants-by-vector.ts`; this
+ * SDK has no runtime dependency on `@materialgraph/products`, so the shapes
+ * are copied here and `contract-parity.test.ts` keeps them honest.
+ */
+import type { ImageReferenceInput } from "./image-reference-types.js";
+import type { FilterGroups, ListVariantsItem } from "./list-variants-types.js";
+export declare const FIND_VARIANTS_BY_VECTOR_MODES: readonly ["text", "image", "text_and_image"];
+export type FindVariantsByVectorMode = (typeof FIND_VARIANTS_BY_VECTOR_MODES)[number];
+export type FindVariantsByVectorQuery = {
+    /** Exactly one reference. Only for image modes. */
+    image?: ImageReferenceInput;
+    mode: FindVariantsByVectorMode;
+    /** Description, mood words included. Only for text modes. */
+    text?: string;
+};
+export type FindVariantsByVectorInput = {
+    /** Attribute or block ids to add. */
+    attributes?: string[];
+    /** Variant ids to leave out. A seed image's own variant is always left out. */
+    excludeVariantIds?: string[];
+    filters?: FilterGroups;
+    /** Default 20. */
+    limit?: number;
+    query: FindVariantsByVectorQuery;
+};
+export type FindVariantsByVectorItem = Omit<ListVariantsItem, "materialBankId"> & {
+    /** The variant's Material Bank SKU; null means none is recorded. Always present here, unlike `list_variants`' optional field. */
+    materialBankId: string | null;
+    /** Voyage cosine to the query. Ranks only; not a probability. */
+    similarity: number;
+};
+export type FindVariantsByVectorReference = {
+    id: string;
+    kind: "url" | "assetId" | "variantId" | "sourceId";
+} | null;
+export type FindVariantsByVectorScan = {
+    /** True when no further candidates match; false means more may exist. */
+    exhausted: boolean;
+    read: number;
+    rejected: number;
+    route: "lane" | "metadata" | "allowlist";
+};
+export type FindVariantsByVectorTimings = {
+    embedMs: number;
+    filterMs: number;
+    referenceMs: number;
+    totalMs: number;
+    vectorMs: number;
+    verifyMs: number;
+};
+export type FindVariantsByVectorOutput = {
+    /** Explicit `{field: "variant", op: "in"}` filter ids that name a real variant outside the materials catalogue — present only when at least one did. */
+    excludedByCorpusScope?: string[];
+    items: FindVariantsByVectorItem[];
+    mode: FindVariantsByVectorMode;
+    reference: FindVariantsByVectorReference;
+    scan: FindVariantsByVectorScan;
+    timings: FindVariantsByVectorTimings;
+    /** Explicit `{field: "variant", op: "in"}` filter ids that named no eligible variant — present only when at least one did. */
+    unresolvedVariantIds?: string[];
+    /** Filtered attributes no variant in scope states at all. Present only on an empty page, so its absence means the empty page is a genuine no-match. */
+    unstated?: string[];
+};

package/find-variants-by-vector-types.js

@@ -0,0 +1,5 @@
+export const FIND_VARIANTS_BY_VECTOR_MODES = [
+    "text",
+    "image",
+    "text_and_image",
+];

package/get-variant-types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module get-variant-types
+ * @description Hand-maintained mirror of `get_variant`'s (MG-2251) input and
+ * output wire shapes. The source of truth is
+ * `packages/products/src/variants/get-variant.ts`, but this SDK has no RUNTIME
+ * dependency on `@materialgraph/products`, so the shapes are copied here and
+ * `__tests__/contract-parity.test.ts` keeps the mirror honest against the
+ * server types.
+ */
+import type { ListVariantsNotApplicable, ListVariantsSpecifications } from "./list-variants-types.js";
+/** The detail to add under `specifications`; absent, the answer is the compact item alone. */
+export type GetVariantOptions = {
+    /** Canonical attribute ids, e.g. `["nrc_rating"]`. */
+    attributes?: readonly string[];
+    /** Canonical block ids, returned whole, e.g. `["acoustic"]`. */
+    blocks?: readonly string[];
+};
+/**
+ * One variant: the compact identity, and `specifications` only for the
+ * attributes and blocks that were asked for. A null value is unknown, never
+ * false or zero.
+ */
+export type GetVariantOutput = {
+    category: {
+        id: string;
+        name: string;
+    };
+    code: string | null;
+    image: {
+        alt: string;
+        url: string;
+    } | null;
+    /** The brand. `id` is the slug `get_brand` takes. */
+    brand: {
+        id: string;
+        name: string;
+    };
+    /** The variant's Material Bank SKU. Absent means none is recorded. */
+    materialBankId?: string;
+    name: string;
+    /** Requested blocks or attributes the variant's product type does not carry. */
+    notApplicable?: ListVariantsNotApplicable;
+    product: {
+        id: string;
+        name: string;
+    };
+    specifications?: ListVariantsSpecifications;
+    url: string | null;
+    variantId: string;
+};

package/get-variant-types.js

@@ -0,0 +1,10 @@
+/**
+ * @module get-variant-types
+ * @description Hand-maintained mirror of `get_variant`'s (MG-2251) input and
+ * output wire shapes. The source of truth is
+ * `packages/products/src/variants/get-variant.ts`, but this SDK has no RUNTIME
+ * dependency on `@materialgraph/products`, so the shapes are copied here and
+ * `__tests__/contract-parity.test.ts` keeps the mirror honest against the
+ * server types.
+ */
+export {};

package/identifiers.d.ts

@@ -15,7 +15,7 @@
  * - **Canonical vocabulary** — `attributeId`, `term`, `productTypeId`,
  *   `categoryKey`, `jurisdictionId`, `brandSlug`. These ARE meaningful, stable,
  *   and yours to compose queries from — but you DISCOVER them rather than
- *   invent them (`specificationFacets()`, `attributeValues()`,
+ *   invent them (`listVariantFacets()`, `listEnumValues()`,
  *   `listAttributes()`, `taxonomy()`, `colourFacets()`, `codes.context()`).
  *   A hand-guessed canonical token is the second-most-common caller bug.
  *

package/identifiers.js

@@ -15,7 +15,7 @@
  * - **Canonical vocabulary** — `attributeId`, `term`, `productTypeId`,
  *   `categoryKey`, `jurisdictionId`, `brandSlug`. These ARE meaningful, stable,
  *   and yours to compose queries from — but you DISCOVER them rather than
- *   invent them (`specificationFacets()`, `attributeValues()`,
+ *   invent them (`listVariantFacets()`, `listEnumValues()`,
  *   `listAttributes()`, `taxonomy()`, `colourFacets()`, `codes.context()`).
  *   A hand-guessed canonical token is the second-most-common caller bug.
  *

package/image-reference-types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @module image-reference-types
+ * @description The one image-reference shape the vector-discovery lenses
+ * share (`@materialgraph/products/vector-discovery/image-reference`'s
+ * `imageReferenceInputSchema`): a catalogue asset, an upload, a public URL,
+ * or an existing variant's own image. Exactly one field is set per call; the
+ * server refuses more than one.
+ */
+export type ImageReferenceInput = {
+    /** Catalogue asset id. */
+    assetId?: string;
+    /** Upload id (`smf_...`) from source-material. */
+    sourceId?: string;
+    /** Public HTTPS image URL. */
+    url?: string;
+    /** Variant whose image to use. */
+    variantId?: string;
+};

package/index.d.ts

@@ -1,28 +1,30 @@
 export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
-export type { MaterialGraphClientOptions, SourceMaterialCommentsNamespace, } 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 "./list-enum-values-types.js";
+export type * from "./get-variant-types.js";
+export type * from "./image-reference-types.js";
+export type * from "./find-variants-by-colour-types.js";
+export { FIND_VARIANTS_BY_VECTOR_MODES } from "./find-variants-by-vector-types.js";
+export type * from "./find-variants-by-vector-types.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
 export type * from "./identifiers.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type * from "./run-types.js";
 export type * from "./citation-types.js";
-export type * from "./material-composition-types.js";
 export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
 export type * from "./search-card-types.js";
-export type * from "./identify-types.js";
+export type * from "./resolve-variant-types.js";
 export type * from "./catalogue-types.js";
 export type * from "./by-colour-types.js";
 export { CategoriesClient } from "./categories-client.js";
 export type * from "./category-types.js";
-export { CodesClient } from "./codes-client.js";
-export type * from "./codes-types.js";
 export { ColoursClient } from "./colours-client.js";
 export type { ColoursTransport } from "./colours-client.js";
-export type * from "./colour-aggregate-types.js";
 export type * from "./palette-search-types.js";
 export type * from "./query-understanding-types.js";
 export type * from "./match-types.js";
@@ -34,7 +36,6 @@ export type * from "./brand-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
-export type * from "./taxonomy-coverage-types.js";
 export type * from "./search-refinement-types.js";
 export type * from "./attribution-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";

package/index.js

@@ -1,9 +1,9 @@
 export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
+export { FIND_VARIANTS_BY_VECTOR_MODES } from "./find-variants-by-vector-types.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
 export { CategoriesClient } from "./categories-client.js";
-export { CodesClient } from "./codes-client.js";
 export { ColoursClient } from "./colours-client.js";
 export { MATCH_ERROR_REASONS, MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";

package/list-enum-values-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module list-enum-values-types
+ * @description Hand-maintained mirror of `list_enum_values`'s (MG-2225) input
+ * and output wire shapes. The source of truth is
+ * `packages/products/src/materials/list-enum-values.ts`; this SDK has no
+ * runtime dependency on `@materialgraph/products`, so the shapes are copied
+ * here and `contract-parity.test.ts` keeps them honest.
+ */
+import type { OpenEnum } from "./types.js";
+/** Options for `listEnumValues()` (GET `/api/v1/catalog/enum-values`). */
+export type ListEnumValuesOptions = {
+    /**
+     * A value dictionary id, from a `listAttributes()` item's `dictionaryId`.
+     * Required without a `query`; with a `query`, omit it to search every
+     * dictionary.
+     */
+    dictionaryId?: string;
+    /** A value name, alias, misspelling or meaning. Omit to browse a dictionary. */
+    query?: string;
+    /** Items per page, 1 to 50. Default 20. */
+    limit?: number;
+    /** `pageInfo.endCursor` from the previous page, with the same query and dictionary. */
+    cursor?: string;
+};
+/** How an item was found. A distance or similarity compares only within one method. */
+export type EnumValueMatch = {
+    method: OpenEnum<"exact" | "alias" | "fuzzy" | "vector">;
+    /** The id, label or alias that matched, or null for a match by meaning. */
+    matchedText: string | null;
+    /** Fuse distance, 0 best. */
+    distance?: number;
+    /** Set when the query named a deprecated term: the active term it was resolved from. */
+    resolvedFrom?: string;
+    /** Cosine similarity, 1 best. */
+    similarity?: number;
+};
+/** One allowed value of a dictionary. */
+export type EnumValueItem = {
+    /** The attributes this value can filter `listVariants()` on; empty when it cannot be filtered on. */
+    attributeIds: string[];
+    /** The taxonomy's definition when the value resolves to a canonical concept, otherwise null. */
+    definition: string | null;
+    dictionaryId: string;
+    label: string;
+    /** Present only when the page answers a query. */
+    match?: EnumValueMatch;
+    /** The bare term id `listVariants()` accepts for any of `attributeIds`. */
+    valueId: string;
+};
+export type ListEnumValuesResult = {
+    /** The dictionary the page was read from; null when a query searched every dictionary. */
+    dictionaryId: string | null;
+    items: EnumValueItem[];
+    pageInfo: {
+        endCursor: string | null;
+        hasNextPage: boolean;
+    };
+};

package/list-variants-types.d.ts

@@ -107,14 +107,14 @@ export type ListVariantsNotApplicable = {
 };
 /**
  * One list item: the compact identity needed to pick a variant, with image
- * and maker page only when requested (`include`) and selected attributes
+ * and brand page only when requested (`include`) and selected attributes
  * under `specifications`. Leaner than `get_variant`'s item on purpose.
  */
 export type ListVariantsItem = {
     category: string;
     code: string | null;
     image?: string | null;
-    maker: {
+    brand: {
         id: string;
         name: string;
     };
@@ -137,6 +137,8 @@ export type ListVariantsItem = {
     variantId: string;
 };
 export type ListVariantsOutput = {
+    /** Explicit `{field: "variant", op: "in"}` ids that name a real variant outside the materials catalogue. Present only when at least one did. */
+    excludedByCorpusScope?: string[];
     items: ListVariantsItem[];
     pageInfo: {
         endCursor: string | null;
@@ -146,4 +148,6 @@ export type ListVariantsOutput = {
     preferenceMatchesRemain?: boolean;
     /** Explicit `{field: "variant", op: "in"}` ids anywhere in `filters.terms` that did not resolve to an eligible variant in the requested `corpusScope`. */
     unresolvedVariantIds?: string[];
+    /** Filtered attributes no variant in scope states at all. Present only on an empty first page, so its absence means the empty page is a genuine no-match. */
+    unstated?: string[];
 };

package/material-asset-types.d.ts

@@ -12,7 +12,7 @@ import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /**
  * `available`: MaterialGraph serves the file at `url`. `unknown`: `url` is the
- * maker's own link, unchecked. `unavailable`: no working copy is known and
+ * brand's own link, unchecked. `unavailable`: no working copy is known and
  * `url` is null.
  */
 export type VariantAssetAvailability = OpenEnum<"available" | "unknown" | "unavailable">;
@@ -51,7 +51,7 @@ export type VariantAssetItem = {
     /** Images only; absent when unknown. */
     width?: number;
 };
-/** Whether the maker's document source was read for this variant. Absent when documents are filtered out. */
+/** Whether the brand's document source was read for this variant. Absent when documents are filtered out. */
 export type VariantDocumentCoverageState = OpenEnum<"available" | "none_declared" | "not_ingested" | "unavailable_source" | "dead_link" | "failed_ingest">;
 export type VariantAssetPageInfo = {
     nextCursor: string | null;
@@ -104,7 +104,8 @@ export type MaterialDocumentProjectionItem = {
         status: MaterialDocumentStatus;
         readable: boolean;
     }[];
-    documentType: string | null;
+    /** Registry purposes, `unknown` filtered out; absent when none is known. */
+    documentTypes?: VariantDocumentType[];
     originalName: string;
     status: MaterialDocumentStatus;
     /** Null for unavailable, dead, or failed source documents. */