@instruments/materialgraph 0.7.1 → 0.8.0

package/types.d.ts

@@ -25,6 +25,7 @@
  *     match set. Follow the cursor for the rest, and never report a page size as
  *     a total.
  */
+import type { ByColourSwatch } from "./by-colour-types.js";
 import type { BySpecVerdict } from "./by-spec-types.js";
 import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { MaterialDetail, MaterialTile } from "./material-types.js";
@@ -39,12 +40,22 @@ export type OpenEnum<T extends string> = T | (string & {});
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-/** One palette swatch of a material's main image. */
+/**
+ * One palette swatch of a material's main image — colour DERIVED FROM PRODUCT
+ * IMAGERY, so read it as visual likeness, never as a declared colour spec.
+ */
 export interface PaletteSwatch {
     hex: string;
     proportion: number;
     /** Stored human colour name for the swatch, when one was extracted. */
     name?: string | null;
+    /**
+     * `hex` in OKLab, derived server-side so you can sort or measure swatches
+     * without converting them yourself. Additive, so optional: the colour lane and
+     * the material record carry it, other surfaces may not, and absent means "not
+     * derived here" — never "achromatic".
+     */
+    oklab?: OklabTriple;
 }
 /** Loose colour metadata for a search result's main image; every field is independently optional. */
 export interface ColourMeta {
@@ -109,6 +120,16 @@ export interface SearchResultItem {
     product: string;
     brandSlug: string | null;
     productId: ProductId | null;
+    /**
+     * The variant's Material Bank SKU — the same `materialBankId` the material
+     * record carries, so a match card can render straight from a result instead of
+     * paying a per-result lookup. Populated on the MATCH lanes (`match()` and
+     * `matchStream()` frames).
+     *
+     * ABSENT means no MB identity is known for the variant — never that the SKU
+     * cannot be ordered. Presence is the orderability tell; absence is silence.
+     */
+    materialBankId?: string;
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
@@ -248,44 +269,6 @@ export interface MatchResponse {
     droppedAsDuplicateProduct: number;
     note?: string;
 }
-/** Coarse group + fine type of a colour match's primary product type. */
-export interface MatchCategory {
-    group: string | null;
-    type: string | null;
-}
-/**
- * One colour-palette match.
- *
- * `hex`, `distance` and `closeness` are OKLab geometry over colour EXTRACTED
- * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report it as visual
- * likeness ("reads close to this colour"), never as a stated colour
- * specification.
- */
-export interface ByColourMatch {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    distance: number;
-    closeness: number;
-    category: MatchCategory | null;
-    oklab: OklabTriple | null;
-}
-/** The `search/colours` response. */
-export interface ByColourResponse {
-    query: {
-        colours: string[];
-        categories?: string[];
-        oklab?: OklabTriple;
-    };
-    /** `matches.length` — THIS PAGE. Not a corpus total; this surface states none. */
-    count: number;
-    matches: ByColourMatch[];
-}
 /** One item from the pure colour-scalar browse. */
 export interface BrowseResultItem {
     /** Opaque — round-trip verbatim. */
@@ -303,6 +286,17 @@ export interface BrowseResultItem {
         vibrancy: number | null;
     };
     retired?: boolean;
+    /**
+     * The row's own image palette — the FULL stored palette of the SAME image
+     * `imageUrl` serves, uncapped and in stored order, each swatch with `oklab`
+     * (see {@link ByColourSwatch}), so a card can render, sort or group colours
+     * without a second call. A one-swatch palette means the extractor found one
+     * colour (solid-colour materials are genuinely monochrome), not that the list
+     * was trimmed. ABSENT when no palette is on record for that image: absent
+     * means unknown, NOT that the material has no colours. These swatches come
+     * from product imagery, not from the manufacturer.
+     */
+    palette?: ByColourSwatch[];
 }
 /**
  * A single page of the colour browse — the SDK's one genuinely cursor-paginated
@@ -508,6 +502,7 @@ export interface ResolveAttributeResponse {
     candidates: AttributeCandidate[];
 }
 export type * from "./catalog-discovery-types.js";
+export type * from "./resolve-types.js";
 export type * from "./suggest-types.js";
 export type * from "./by-spec-types.js";
 export interface WhoamiResponse {
@@ -626,20 +621,6 @@ export interface SearchGetParams {
     /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
     view?: OpenEnum<"full" | "card">;
 }
-/** Params for `search/colours`. */
-export interface ByColourParams {
-    /** A single hex (with or without `#`). */
-    hex?: string;
-    /** A palette — repeated as one `colour` query entry each. */
-    colour?: string | string[];
-    /** OKLab triple (all-or-none). */
-    l?: number;
-    a?: number;
-    b?: number;
-    /** HARD category filter — display names or taxonomy ids (repeatable). */
-    category?: string | string[];
-    limit?: number;
-}
 /** Params for the pure colour `search/browse` surface. */
 export interface BrowseParams {
     sort: OpenEnum<"light" | "dark" | "vivid" | "muted" | "colourful">;
@@ -650,7 +631,13 @@ export interface BrowseParams {
     cursor?: Cursor;
     /** Page size. */
     limit?: number;
-    /** Comma-separated product-type ids to restrict the browse to. */
+    /**
+     * Comma-separated taxonomy keys to restrict the browse to, at EITHER tier of
+     * `/api/v1/taxonomy/categories`. A GROUP key (`tile_surfaces`) expands to
+     * every product type under it, a TYPE key (`ceramic_porcelain_tile`) stands
+     * for itself, and a mixed list is their deduplicated union. A key in neither
+     * tier is a 400 listing the valid keys — never an empty page.
+     */
     types?: string;
 }
 /** The Material Match request body — exactly one of `imageBase64`, `imageUrl`, `vector`. */