@instruments/materialgraph 0.33.0 → 0.35.0

package/material-block-types.d.ts

@@ -7,7 +7,7 @@
  * "nobody has looked". This projection is the one read that says WHICH, per
  * field, in {@link MaterialCoverageStatus}. When a caller needs to render a
  * negative ("this material carries no fire rating") rather than an unknown, this
- * is the only surface entitled to back it: a `verified` field with a `false` /
+ * is the only surface entitled to back it: a `complete` field with a `false` /
  * `0` / `[]` value. Never derive a negative from a value's absence elsewhere.
  */
 import type { VariantId } from "./identifiers.js";
@@ -15,7 +15,7 @@ import type { OpenEnum } from "./types.js";
 /**
  * Coverage status, shared by blocks and fields.
  *
- * `verified` — determined. For a field a value is known, INCLUDING `false`, `0`
+ * `complete` — determined. For a field a value is known, INCLUDING `false`, `0`
  * and `[]`, which are answers meaning "we looked and there is none". For a
  * block, every field is determined.
  * `partial` — determined for some fields but not all.
@@ -24,29 +24,29 @@ import type { OpenEnum } from "./types.js";
  * `not_applicable` — cannot apply to this product type. Never work, never a gap.
  *
  * BREAKING in this release: blocks previously reported `populated`/`pending`
- * while fields reported `verified`/`missing` — two spellings of one concept
+ * while fields reported `complete`/`missing` — two spellings of one concept
  * that disagreed with each other on the same variant. Map `populated ->
- * verified` and `pending -> missing`. Both types are retained as aliases so
+ * complete` and `pending -> missing`. Both types are retained as aliases so
  * existing code keeps compiling; they now describe the same set.
  *
  * The authoritative list is served at runtime by
  * `get-schema { kind: "coverageStatuses" }`.
  */
-export type MaterialCoverageStatus = OpenEnum<"verified" | "partial" | "missing" | "not_applicable">;
+export type MaterialCoverageStatus = OpenEnum<"complete" | "partial" | "missing" | "not_applicable">;
 export type MaterialBlockStatus = MaterialCoverageStatus;
 export type MaterialBlockFieldStatus = MaterialCoverageStatus;
 /**
  * A field's value. `null` is AMBIGUOUS on its own — pair it with `status`:
- * `verified` + `null` is a determined absence, `missing` + `null` is unread.
+ * `complete` + `null` is a determined absence, `missing` + `null` is unread.
  */
 export type MaterialBlockFieldValue = string | number | boolean | unknown[] | Record<string, unknown> | null;
 /**
  * One field of a block. READ `status` BEFORE `value` — a `false` under
- * `status: "verified"` is a real negative you may publish; the same `false`
+ * `status: "complete"` is a real negative you may publish; the same `false`
  * under `missing` is a placeholder for an unanswered question.
  */
 export type MaterialBlockProjectionField = {
-    /** Canonical vocabulary, not an opaque id — the same token `bySpec` accepts. */
+    /** Canonical vocabulary, not an opaque id - the same token `listVariants` filters accept. */
     attributeId: string;
     label: string;
     value: MaterialBlockFieldValue;
@@ -55,7 +55,7 @@ export type MaterialBlockProjectionField = {
     unit?: string;
     status: MaterialBlockFieldStatus;
     /** Provenance supplied by the graph when a source-backed claim supports this field. */
-    sourceBasis?: string;
+    valueOrigin?: string;
     /** Claim confidence supplied by the graph; absence means no confidence was emitted. */
     confidence?: number;
 };

package/material-types.d.ts

@@ -17,14 +17,14 @@ import type { VariantId } from "./identifiers.js";
  * there is none" apart from "nobody has looked" — that is the only projection
  * that says which.
  */
-import type { ImageSource, MaterialColour, OpenEnum } from "./types.js";
+import type { ImageSource, MaterialColor, OpenEnum } from "./types.js";
 /**
  * Whether a material can still be bought.
  *
  *  - `available` — listed in the catalog of record.
  *  - `discontinued` — WITHDRAWN from that catalog. This is the source's own
- *    listing state, not a reviewed manufacturer-discontinuation claim; do not
- *    present it as the manufacturer having discontinued the product.
+ *    listing state, not a reviewed brand-discontinuation claim; do not
+ *    present it as the brand having discontinued the product.
  *  - `superseded` — a reviewed product relationship names a successor and the
  *    material is no longer listed.
  *  - `unknown` — never checked. A real answer, not an error.
@@ -45,16 +45,18 @@ export type MaterialTile = {
     imageUrl: string | null;
     imageSource: ImageSource | null;
     category: string | null;
-    colour: MaterialColour;
+    /** All accepted source category ids in source order; empty when unknown. */
+    categories: string[];
+    color: MaterialColor;
     availability: MaterialAvailability;
     /**
-     * The accepted Colour Name attribute — the colourway's true name where
+     * The accepted Color Name attribute — the colorway's true name where
      * `variantName` collapsed to the product's (MG-940: 83.7% of visible
-     * colourway families name every variant after the product, e.g. all 10 CF
-     * Stinson "Drift" colourways share `variantName: "Drift"`). Absent means
+     * colorway families name every variant after the product, e.g. all 10 CF
+     * Stinson "Drift" colorways share `variantName: "Drift"`). Absent means
      * the attribute is absent — never render a missing key as "unnamed".
      */
-    colourName?: string;
+    colorName?: string;
 };
 /** A retained product-type proposal. It is review evidence, never a category. */
 type ProposedProductType = {

package/operations.d.ts

@@ -1,5 +1,5 @@
-export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["samplizeColorVecCache", "GET", "/api/v1/catalogues/samplize/colorvec", "samplize_colorvec_cache"], readonly ["samplizeCatalogueSearch", "POST", "/api/v1/catalogues/samplize/search", "samplize_catalogue_search"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], readonly ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColour", "POST", "/api/v1/variants/by-colour", "find_variants_by_colour"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findCompanions", "POST", "/api/v1/variants/companions", "find_companions"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["workflows.start", "POST", "/api/v1/workflows/{workflowId}/runs", "create_public_run"], readonly ["workflows.run", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}", "get_public_run"], readonly ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
+export declare const MATERIALGRAPH_API_VERSION = "0.8.0";
+declare const OPERATION_DEFINITIONS: readonly [readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], readonly ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColor", "POST", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findCompanions", "POST", "/api/v1/variants/companions", "find_companions"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColor", "GET", "/api/v1/search/colors/resolve", "resolve_color_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colors.profiles", "GET", "/api/v1/colors/profiles", "get_category_color_profiles"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["workflows.start", "POST", "/api/v1/workflows/{workflowId}/runs", "create_public_run"], readonly ["workflows.run", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}", "get_public_run"], readonly ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -1,18 +1,6 @@
 import { MaterialGraphError } from "./errors.js";
-export const MATERIALGRAPH_API_VERSION = "0.7.0";
+export const MATERIALGRAPH_API_VERSION = "0.8.0";
 const OPERATION_DEFINITIONS = [
-    [
-        "samplizeColorVecCache",
-        "GET",
-        "/api/v1/catalogues/samplize/colorvec",
-        "samplize_colorvec_cache",
-    ],
-    [
-        "samplizeCatalogueSearch",
-        "POST",
-        "/api/v1/catalogues/samplize/search",
-        "samplize_catalogue_search",
-    ],
     ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
     [
         "catalogPages",
@@ -32,16 +20,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/catalogs/{catalogId}/references",
         "list_catalog_product_references",
     ],
-    ["search", "POST", "/api/v1/search", "search_materials_post"],
-    ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"],
     [
         "samplizeCatalogue",
         "GET",
         "/api/v1/catalogues/samplize/products",
         "samplize_catalogue_products",
     ],
-    ["searchGet", "GET", "/api/v1/search", "search_materials_get"],
-    ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"],
     [
         "catalogueReferences",
         "POST",
@@ -112,10 +96,10 @@ const OPERATION_DEFINITIONS = [
     ],
     ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"],
     [
-        "findVariantsByColour",
+        "findVariantsByColor",
         "POST",
-        "/api/v1/variants/by-colour",
-        "find_variants_by_colour",
+        "/api/v1/variants/by-color",
+        "find_variants_by_color",
     ],
     [
         "findVariantsByVector",
@@ -127,10 +111,10 @@ const OPERATION_DEFINITIONS = [
     ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"],
     ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"],
     [
-        "resolveColour",
+        "resolveColor",
         "GET",
-        "/api/v1/search/colours/resolve",
-        "resolve_colour_name",
+        "/api/v1/search/colors/resolve",
+        "resolve_color_name",
     ],
     [
         "listAttributes",
@@ -147,7 +131,12 @@ const OPERATION_DEFINITIONS = [
     ["categories.list", "GET", "/api/v1/categories", "list_categories"],
     ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"],
     ["whoami", "GET", "/api/v1/whoami", "whoami"],
-    ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"],
+    [
+        "colors.profiles",
+        "GET",
+        "/api/v1/colors/profiles",
+        "get_category_color_profiles",
+    ],
     [
         "extractPalette",
         "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "type": "module",
   "exports": {
     ".": {
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@instruments/colorscope": "9.0.1"
+    "@instruments/colorscope": "^10.2.0"
   },
   "license": "Proprietary",
   "engines": {

package/{resolve-colour-types.d.ts → resolve-color-types.d.ts}

@@ -1,22 +1,22 @@
 import type { MatchTarget } from "@instruments/colorscope/match";
 /**
- * Colour-name resolution (GET `/api/v1/search/colours/resolve`): the resolved
- * colour, and whether the named paint is a variant in the catalogue.
+ * Color-name resolution (GET `/api/v1/search/colors/resolve`): the resolved
+ * color, and whether the named paint is a variant in the catalogue.
  */
 import type { ColorResolution } from "@instruments/colorscope/naming";
-import type { CorpusScope } from "./corpus-scope-types.js";
 import type { VariantId } from "./identifiers.js";
+import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
 import type { OpenEnum } from "./types.js";
-/** Options for `resolveColour`. */
-export type ResolveColourOptions = {
+/** Options for `resolveColor`. */
+export type ResolveColorOptions = {
     /**
      * Sets `inScope` on each catalogue variant the lookup reports. It never
      * narrows the lookup. Absent leaves every `inScope` null.
      */
-    corpusScope?: CorpusScope;
+    searchCatalogueSubset?: SearchCatalogueSubset;
 };
 /** One catalogue variant carrying the named paint. */
-export type ResolveColourCatalogueVariant = {
+export type ResolveColorCatalogueVariant = {
     variantId: VariantId;
     /** The brand exactly as stored, suspect or not. */
     brand: {
@@ -28,32 +28,32 @@ export type ResolveColourCatalogueVariant = {
     inScope: boolean | null;
     /**
      * True when the stored brand is Samplize, a sampling channel, and the listing
-     * is not Samplize's own: the colour is another brand's, so `brand` is not who
+     * is not Samplize's own: the color is another brand's, so `brand` is not who
      * made it. The variant is still the right one for the name.
      */
     parentageSuspect: boolean;
 };
 /**
  * Whether the named paint is a variant in the catalogue. Exact, global, and
- * never narrowed by `corpusScope`, and run only for a `brand` library hit.
+ * never narrowed by `searchCatalogueSubset`, and run only for a `brand` library hit.
  * `not-in-catalogue` means the catalogue was searched and nothing carries the
  * paint; `not-looked-up` means there was no one brand's paint to search for.
  */
-export type ResolveColourVariant = ({
+export type ResolveColorVariant = ({
     status: "matched";
-} & ResolveColourCatalogueVariant) | {
+} & ResolveColorCatalogueVariant) | {
     status: "ambiguous";
-    candidates: ResolveColourCatalogueVariant[];
+    candidates: ResolveColorCatalogueVariant[];
 } | {
     status: "not-in-catalogue";
 } | {
     status: "not-looked-up";
-    reason: OpenEnum<"reference-colour" | "descriptive-colour" | "no-paint-identity" | "generic-colour" | "several-paints">;
+    reason: OpenEnum<"reference-color" | "descriptive-color" | "no-paint-identity" | "generic-color" | "several-paints">;
 };
-export type ResolveColourResponse = {
+export type ResolveColorResponse = {
     /** Examples within the governed range. They do not replace its representative or bounds. */
     rangeSamples?: string[];
-    /** Explicit manufacturer choices for an ambiguous paint name. Never selected automatically. */
+    /** Explicit brand choices for an ambiguous paint name. Never selected automatically. */
     alternatives?: {
         query: string;
         name: string;
@@ -69,15 +69,15 @@ export type ResolveColourResponse = {
         hex: string;
         name: string;
         code?: string;
-        /** The ColorScope library the colour resolved in. Not necessarily a brand. */
+        /** The ColorScope library the color resolved in. Not necessarily a brand. */
         libraryId?: string;
         /**
-         * The library's own type: `brand` is a brand's paint, `reference` a colour
+         * The library's own type: `brand` is a brand's paint, `reference` a color
          * standard (RAL, Pantone, HKS), `core` ColorScope's descriptive vocabulary.
          * Present exactly when `libraryId` is. Only a `brand` hit is looked up.
          */
         libraryType?: OpenEnum<"brand" | "reference" | "core" | "consumer">;
         /** The catalogue lookup for the name. Absent from servers that predate it. */
-        variant?: ResolveColourVariant;
+        variant?: ResolveColorVariant;
     } | null;
 };

package/response-schemas.generated.d.ts

@@ -1,5 +1,5 @@
 /** The API contract version the schemas were generated from. */
-export declare const RESPONSE_SCHEMA_API_VERSION = "0.7.0";
+export declare const RESPONSE_SCHEMA_API_VERSION = "0.8.0";
 /** Every SDK operation whose success response has a published JSON Schema. */
-export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["samplize_colorvec_cache", "samplize_catalogue_search", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "search_materials_post", "plan_material_query", "samplize_catalogue_products", "search_materials_get", "search_by_colour", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_colour", "find_variants_by_vector", "find_companions", "resolve_variant", "get_variant", "resolve_colour_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "search_by_palette", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run", "get_verdict_citation"];
+export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "samplize_catalogue_products", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_companions", "resolve_variant", "get_variant", "resolve_color_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "get_category_color_profiles", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run", "get_verdict_citation"];
 export declare const RESPONSE_SCHEMA_CATALOGUE_JSON: string;