@instruments/materialgraph 0.29.0 → 0.31.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/errors.d.ts

@@ -89,7 +89,7 @@ type TransportErrorInput = {
  * member to a problem response means adding it here too, and
  * `problem-extension-parity.test.ts` fails when the two disagree.
  */
-export declare const MATERIALGRAPH_PROBLEM_EXTENSIONS: readonly ["ambiguous_brands", "brand_candidates", "content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "orderable_attributes", "populated_alternatives", "refused_criteria", "unknown_attributes", "unknown_brands", "unknown_fields", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
+export declare const MATERIALGRAPH_PROBLEM_EXTENSIONS: readonly ["ambiguous_brands", "brand_candidates", "content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "orderable_attributes", "populated_alternatives", "refused_criteria", "unknown_attributes", "unknown_brands", "unknown_fields", "unknown_parameters", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
 /** The one error class thrown by all SDK transport and HTTP failures. */
 export declare class MaterialGraphError extends Error {
     readonly kind: MaterialGraphErrorKind;

package/errors.js

@@ -36,6 +36,7 @@ export const MATERIALGRAPH_PROBLEM_EXTENSIONS = [
     "unknown_attributes",
     "unknown_brands",
     "unknown_fields",
+    "unknown_parameters",
     "unorderable_attribute",
     "valid_group_keys",
     "valid_type_keys",

package/find-companions-types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @module find-companions-types
+ * @description Hand-maintained mirror of `find_companions`' (MG-2332) input and
+ * output wire shapes. The source of truth is
+ * `packages/products/src/cospec/schema.ts` (`findCompanionsInputSchema`,
+ * `findCompanionsResultSchema`). 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,
+ * the project-type list included.
+ */
+/** The closed sector vocabulary co-specification evidence is tagged with. */
+export type CompanionProjectType = "Workplace" | "Residential" | "Institution Education" | "Hospitality: Hotel" | "Mixed-Use & Multi-Unit Residential" | "Healthcare" | "Hospitality: Restaurant" | "Government" | "Senior Living" | "Retail" | "Other" | "Sports Entertainment" | "Wellness" | "Medical Dental" | "Aviation" | "Industrial" | "Tech" | "Transportation" | "Single Family" | "Condominium Cooperative" | "Marine" | "Power & Energy" | "University Design Program: Interior Design" | "Non-Billable" | "University Design Program: Interior Architecture" | "University Design Program: Architecture" | "Historic Preservation";
+/** At least one of `variantIds` and `materials`, at most twelve together. */
+export type FindCompanionsInput = {
+    /** Optional row fields: image adds imageUrl, colour adds swatches. */
+    include?: ("image" | "colour")[];
+    /** Ops and audit switch: leave sample cards in. Default false. */
+    includeSamplingArtifacts?: boolean;
+    /** Companions to return, default 20, at most 100. */
+    limit?: number;
+    /** Names to resolve when you hold no ids. Misses come back unresolved. */
+    materials?: string[];
+    /** Only companions sampled together in projects of this sector. */
+    projectType?: CompanionProjectType;
+    /** Variants to find companions for. */
+    variantIds?: string[];
+};
+export type FindCompanionsRow = {
+    brand: string;
+    /** Palette likeness to the seeds. Present with `include: ["colour"]`; never reorders. */
+    colourFit?: number | null;
+    /** Present with `include: ["image"]`. */
+    imageUrl?: string | null;
+    /** Mean lift over the seeds it pairs with; above 1 is above average. */
+    lift: number;
+    product: string;
+    /** Why it was suggested, in one line. */
+    reason: string;
+    /** `companion` is another brand; `brand_sibling` and `colourway` share the seed's. */
+    relation: "companion" | "brand_sibling" | "colourway";
+    /** How many seeds it was sampled with. */
+    seedMatchCount: number;
+    /** Present with `include: ["colour"]`. */
+    swatches?: {
+        hex: string;
+        proportion: number;
+    }[];
+    variantId: string;
+    variantName: string | null;
+};
+export type FindCompanionsOutput = {
+    /** Strongest first: seeds matched, then summed lift, one row per product. */
+    companions: FindCompanionsRow[];
+    /** The seeds as resolved, so a caller sees what a name became. */
+    seeds: {
+        brand: string;
+        /** Present with `include: ["image"]`. */
+        imageUrl?: string | null;
+        product: string;
+        /** The id or name this seed came from. */
+        resolvedFrom: string;
+        variantId: string;
+        variantName: string | null;
+    }[];
+    /** Seed ids outside the materials catalogue; present only when at least one was. */
+    excludedByCorpusScope?: string[];
+    /** References that matched no variant. */
+    unresolved: string[];
+};

package/find-companions-types.js

@@ -0,0 +1,12 @@
+/**
+ * @module find-companions-types
+ * @description Hand-maintained mirror of `find_companions`' (MG-2332) input and
+ * output wire shapes. The source of truth is
+ * `packages/products/src/cospec/schema.ts` (`findCompanionsInputSchema`,
+ * `findCompanionsResultSchema`). 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,
+ * the project-type list included.
+ */
+export {};

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/http-transport.d.ts

@@ -1,6 +1,6 @@
 import type { RateLimit } from "./errors.js";
 import type { SdkOperation } from "./operations.js";
-export type QueryValue = string | number | boolean | undefined | null | (string | number | boolean)[];
+type QueryValue = string | number | boolean | undefined | null | (string | number | boolean)[];
 export type QueryParams = Record<string, QueryValue>;
 export type RequestOptions = {
     /** Required by state-changing operations that support safe retries. */

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,31 @@
 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-companions-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 +37,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";