@instruments/materialgraph 0.32.0 → 0.35.0

package/client.js

@@ -3,8 +3,8 @@ import { listBrands } from "./brands-client.js";
 import { CatalogueClient } from "./catalogue-client.js";
 import { CategoriesClient } from "./categories-client.js";
 import { DEFAULT_BASE_URL } from "./client-config.js";
-import { listAttributes as listAttributesCall, listEnumValues as listEnumValuesCall, resolveColour as resolveColourCall, } from "./client-vocabulary.js";
-import { ColoursClient } from "./colours-client.js";
+import { listAttributes as listAttributesCall, listEnumValues as listEnumValuesCall, resolveColor as resolveColorCall, } from "./client-vocabulary.js";
+import { ColorsClient } from "./colors-client.js";
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
 import { listVariantAssets as listVariantAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
@@ -23,25 +23,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.
@@ -53,10 +55,10 @@ export 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
@@ -65,17 +67,19 @@ export class MaterialGraphClient extends CatalogueClient {
      */
     categories;
     /**
-     * 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.
      */
-    colours;
+    colors;
     /**
      * THE QUESTION: "do a whole job for me" — the ASYNC lens. `start()` begins a
      * Run of one registered workflow, `run()` polls it, `streamRunEvents()` and
@@ -100,9 +104,8 @@ export class MaterialGraphClient extends CatalogueClient {
         this.categories = new CategoriesClient({
             get: async (operationId, query, signal, pathParams) => await this.#get(operationId, query, signal, pathParams),
         });
-        this.colours = new ColoursClient({
+        this.colors = new ColorsClient({
             get: async (operationId, query, signal) => await this.#get(operationId, query, signal),
-            post: async (operationId, body, signal) => await this.#post(operationId, body, signal),
         });
         this.workflows = new WorkflowsClient({ transport });
     }
@@ -123,46 +126,6 @@ export class MaterialGraphClient extends CatalogueClient {
             signal,
         });
     }
-    async search(input, signal) {
-        return await this.#post("search_materials_post", input, signal);
-    }
-    /** Whole materials ask → inspectable meanings and complete safe search requests. */
-    async planQuery(query, signal) {
-        return await this.#post("plan_material_query", { query }, signal);
-    }
-    async searchGet(params, signal) {
-        return await this.#get("search_materials_get", { ...params }, signal);
-    }
-    /**
-     * 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.
-     */
-    async byColour(params, signal) {
-        return await this.#get("search_by_colour", {
-            a: params.a,
-            b: params.b,
-            brand: params.brand,
-            category: params.category,
-            colour: params.colour,
-            corpusScope: params.corpusScope,
-            family: params.family,
-            hex: params.hex,
-            l: params.l,
-            limit: params.limit,
-            maxColourDistance: params.maxColourDistance,
-            order: params.order,
-            q: params.q,
-            variantId: params.variantId,
-        }, signal);
-    }
     // ── Materials ──────────────────────────────────────────────────────────────
     /**
      * THE QUESTION: "tell me about THIS variant" (GET
@@ -174,10 +137,10 @@ export 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.
      */
@@ -212,11 +175,11 @@ export 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.
      */
@@ -225,11 +188,11 @@ export class MaterialGraphClient extends CatalogueClient {
             variantId,
         });
     }
-    /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
+    /** "What finishes does the brand declare for THIS product?" - {@link declaredFinishes}. */
     async associatedFinishes(variantId, options, signal) {
         return await assoc.declaredFinishes(this.#transport, variantId, options, signal);
     }
-    /** "What products does the manufacturer declare THIS finish for?" — {@link declaredProducts}. */
+    /** "What products does the brand declare THIS finish for?" - {@link declaredProducts}. */
     async associatedProducts(variantId, options, signal) {
         return await assoc.declaredProducts(this.#transport, variantId, options, signal);
     }
@@ -240,19 +203,21 @@ export class MaterialGraphClient extends CatalogueClient {
      * 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.
      */
     async listVariants(input, signal) {
         return await this.#get("list_variants", {
@@ -260,7 +225,8 @@ export class MaterialGraphClient extends CatalogueClient {
                 ? input.attributes.join(",")
                 : undefined,
             collapse: input.collapse,
-            corpusScope: input.corpusScope,
+            colors: input.colors?.length ? JSON.stringify(input.colors) : undefined,
+            searchCatalogueSubset: input.searchCatalogueSubset,
             cursor: input.cursor,
             filters: input.filters ? JSON.stringify(input.filters) : undefined,
             include: input.include?.length ? input.include.join(",") : undefined,
@@ -272,6 +238,7 @@ export class MaterialGraphClient extends CatalogueClient {
             orderBy: input.orderBy?.length
                 ? JSON.stringify(input.orderBy)
                 : undefined,
+            words: input.words?.length ? input.words.join(",") : undefined,
         }, signal);
     }
     /**
@@ -279,23 +246,39 @@ export 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.
      */
     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).
-     * 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).
      */
-    async findVariantsByColour(input, signal) {
-        return await this.#post("find_variants_by_colour", input, signal);
+    async findVariantsByColor(input, signal) {
+        return await this.#post("find_variants_by_color", input, signal);
     }
     /**
      * THE QUESTION: "what did designers sample together with these?" (POST
@@ -303,7 +286,7 @@ export class MaterialGraphClient extends CatalogueClient {
      * `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.
      */
@@ -315,16 +298,17 @@ export 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.
      */
     async findVariantsByVector(input, signal) {
         return await this.#post("find_variants_by_vector", input, signal);
     }
-    /** Resolve a colour name to its hex, and the named paint's catalogue variant. */
-    async resolveColour(name, signal, options) {
-        return await resolveColourCall(this.#transport, name, signal, options);
+    /** Resolve a color name to its hex, and the named paint's catalogue variant. */
+    async resolveColor(name, signal, options) {
+        return await resolveColorCall(this.#transport, name, signal, options);
     }
     // ── Catalog ──────────────────────────────────────────────────────────────────
     /**
@@ -352,8 +336,8 @@ export class MaterialGraphClient extends CatalogueClient {
     async listEnumValues(options, signal) {
         return await listEnumValuesCall(this.#transport, options, signal);
     }
-    // Hard-specification search (formerly `bySpec()`, GET
-    // `/api/v1/search/specifications`) moved to {@link MaterialGraphClient.listVariants}
+    // Hard-specification search (formerly `bySpec()`) moved to
+    // {@link MaterialGraphClient.listVariants}
     // (MG-2222): each `attribute:value` criterion is one `filters` condition —
     // `{field: attributeId, op: "in", values: [...]}` in `filters.terms` for a
     // term, `{field: attributeId, op: "gte"/"lte"/etc, value}` in
@@ -369,13 +353,12 @@ export class MaterialGraphClient extends CatalogueClient {
     async whoami(signal) {
         return await this.#get("whoami", undefined, signal);
     }
-    // ── Colour helpers (extract) ─────────────────────────────────────────────────
+    // ── Color helpers (extract) ─────────────────────────────────────────────────
     /**
-     * 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"`).
      */
     async extractPalette(input, signal) {
         return await this.#post("extract_image_palette", input, signal);

package/color-profiles-types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Wire types for the category color profile read - GET
+ * `/api/v1/colors/profiles`.
+ *
+ * Kept out of `types.ts` because the shared mirror is at its source-size
+ * budget. Same tolerant-parsing contract as
+ * the rest of the mirror - response enums are widened so a new server value
+ * still type-checks.
+ */
+import type { OpenEnum } from "./types.js";
+/**
+ * Which taxonomy tier a profile's `categoryKey` names, or `"merged"` where the
+ * key is a composite over a caller-defined key set rather than a taxonomy node.
+ */
+export type CategoryTier = OpenEnum<"group" | "type" | "merged">;
+/** One representative color bucket of a category. */
+export type CategoryColor = {
+    hex: string;
+    oklab: {
+        l: number;
+        a: number;
+        b: number;
+    };
+    variantCount: number;
+    /** This bucket's share of the selection's colored variants, 0 to 1. */
+    proportion: number;
+};
+export type CategoryColorProfile = {
+    categoryKey: string;
+    level: CategoryTier;
+    name: string;
+    path: string;
+    /**
+     * Under `groupBy: "merged"`, the requested keys in composite-key order, so
+     * `categoryKey` never has to be split. Absent on a single-category profile.
+     */
+    members?: string[];
+    variantCount: number;
+    avgLightness: number;
+    avgChroma: number;
+    colors: CategoryColor[];
+};
+/**
+ * The snapshot a profile response was computed from. `variantCount` is the
+ * size of the whole materialized view across every category, not of the
+ * selection; `refreshedAt` is its age.
+ */
+export type CategoryColorProfilesBasis = {
+    variantCount: number;
+    refreshedAt: string | null;
+};
+export type CategoryColorProfilesResponse = {
+    profiles: CategoryColorProfile[];
+    basis: CategoryColorProfilesBasis;
+};
+/** Request parameters for `colors.profiles()`. */
+export type ColorProfilesParams = {
+    /** 1 to 8 category keys, at the tier named by `groupBy`. */
+    productTypeIds: readonly string[];
+    /**
+     * `"type"` (the default) names product types. `"group"` merges each group's
+     * leaf product types into one palette; `"merged"` merges EVERY key's leaves
+     * into a single combined palette.
+     */
+    groupBy?: "group" | "type" | "merged";
+    /** Representative colors per category, 1 to 64. The server defaults to 8. */
+    topN?: number;
+    /** `"diverse"` maximises visual distinctness instead of frequency. */
+    select?: "frequency" | "diverse";
+};

package/colors-client.d.ts

@@ -0,0 +1,76 @@
+import type { CategoryColorProfilesResponse, ColorProfilesParams } from "./color-profiles-types.js";
+import type { QueryParams } from "./http-transport.js";
+import type { SdkOperationId } from "./operations.js";
+/**
+ * The color surface, namespaced as `mg.colors` - `profiles`, the colors a
+ * category comes in.
+ *
+ * A namespace rather than a flat method on an already-large client facade.
+ *
+ * The namespace holds no transport of its own: the client hands it a bound
+ * `get`, so auth, rate-limit accounting and error shaping stay in one place.
+ *
+ * `profiles` is an aggregate and carries a `basis`: it reads a materialized
+ * view refreshed on a schedule, not on write, so check how much of the corpus
+ * the answer covers before treating it as complete.
+ *
+ * ROUTING OUT OF THIS NAMESPACE. Color is a lens, and this is not the only
+ * door into it:
+ * - One or several colors → `mg.findVariantsByColor({ mode: "palette", colors })`.
+ * - A color NAME rather than a hex → `mg.resolveColor(name)` first.
+ * - Color WORDS (families, moods, undertones) → `mg.listEnumValues()` for the
+ *   terms, `mg.listVariantFacets()` for how many variants carry each.
+ * - Walking the corpus by lightness/vividness → `mg.listVariants({ orderBy })`.
+ * - Color as one signal among words → `mg.searchVariants(...)`.
+ *
+ * And the honesty rule the whole lens rests on: every color here is DERIVED
+ * FROM PRODUCT IMAGERY, not declared by the brand. Report visual
+ * likeness, never a stated color specification.
+ */
+/** The client's own request primitives, handed down so this file owns no transport. */
+export type ColorsTransport = {
+    get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
+};
+export declare class ColorsClient {
+    #private;
+    constructor(transport: ColorsTransport);
+    /**
+     * THE QUESTION: "what colors does this CATEGORY come in?" - the
+     * representative palette of 1 to 8 categories in ONE call (GET
+     * `/api/v1/colors/profiles`).
+     *
+     * An aggregate over a category, not a list of materials: use
+     * `mg.findVariantsByColor()` or `mg.searchVariants()` when you want the
+     * materials themselves. Check `basis` -
+     * this reads a scheduled materialized view, so it can lag the catalogue.
+     *
+     * `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 color data comes back as a zero-count profile,
+     * not a missing key. Category keys come from `mg.categories.list()`.
+     *
+     * @example
+     * const { profiles, basis } = await mg.colors.profiles({
+     *   productTypeIds: ["wood_surface", "wood_flooring"],
+     *   groupBy: "merged",
+     *   select: "diverse",
+     *   topN: 12,
+     * });
+     * // profiles[0].members is ["wood_flooring", "wood_surface"]; check
+     * // basis.refreshedAt before presenting the palette as current.
+     */
+    profiles(params: ColorProfilesParams, signal?: AbortSignal): Promise<CategoryColorProfilesResponse>;
+}

package/colors-client.js

@@ -0,0 +1,52 @@
+export class ColorsClient {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /**
+     * THE QUESTION: "what colors does this CATEGORY come in?" - the
+     * representative palette of 1 to 8 categories in ONE call (GET
+     * `/api/v1/colors/profiles`).
+     *
+     * An aggregate over a category, not a list of materials: use
+     * `mg.findVariantsByColor()` or `mg.searchVariants()` when you want the
+     * materials themselves. Check `basis` -
+     * this reads a scheduled materialized view, so it can lag the catalogue.
+     *
+     * `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 color data comes back as a zero-count profile,
+     * not a missing key. Category keys come from `mg.categories.list()`.
+     *
+     * @example
+     * const { profiles, basis } = await mg.colors.profiles({
+     *   productTypeIds: ["wood_surface", "wood_flooring"],
+     *   groupBy: "merged",
+     *   select: "diverse",
+     *   topN: 12,
+     * });
+     * // profiles[0].members is ["wood_flooring", "wood_surface"]; check
+     * // basis.refreshedAt before presenting the palette as current.
+     */
+    async profiles(params, signal) {
+        return await this.#transport.get("get_category_color_profiles", {
+            groupBy: params.groupBy,
+            productTypeIds: params.productTypeIds.join(","),
+            select: params.select,
+            topN: params.topN,
+        }, signal);
+    }
+}

package/find-companions-types.d.ts

@@ -13,8 +13,8 @@
 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")[];
+    /** Optional row fields: image adds imageUrl, color adds swatches. */
+    include?: ("image" | "color")[];
     /** Ops and audit switch: leave sample cards in. Default false. */
     includeSamplingArtifacts?: boolean;
     /** Companions to return, default 20, at most 100. */
@@ -28,8 +28,8 @@ export type FindCompanionsInput = {
 };
 export type FindCompanionsRow = {
     brand: string;
-    /** Palette likeness to the seeds. Present with `include: ["colour"]`; never reorders. */
-    colourFit?: number | null;
+    /** Palette likeness to the seeds. Present with `include: ["color"]`; never reorders. */
+    colorFit?: number | null;
     /** Present with `include: ["image"]`. */
     imageUrl?: string | null;
     /** Mean lift over the seeds it pairs with; above 1 is above average. */
@@ -37,11 +37,11 @@ export type FindCompanionsRow = {
     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";
+    /** `companion` is another brand; `brand_sibling` and `colorway` share the seed's. */
+    relation: "companion" | "brand_sibling" | "colorway";
     /** How many seeds it was sampled with. */
     seedMatchCount: number;
-    /** Present with `include: ["colour"]`. */
+    /** Present with `include: ["color"]`. */
     swatches?: {
         hex: string;
         proportion: number;
@@ -64,7 +64,7 @@ export type FindCompanionsOutput = {
         variantName: string | null;
     }[];
     /** Seed ids outside the materials catalogue; present only when at least one was. */
-    excludedByCorpusScope?: string[];
+    excludedBySearchCatalogueSubset?: string[];
     /** References that matched no variant. */
     unresolved: string[];
 };