@instruments/materialgraph 0.18.0 → 0.19.0

package/client.js

@@ -5,6 +5,7 @@ import { HttpTransport } from "./http-transport.js";
 // Aliased to `operation` — the local name every call site here already used.
 import { resolveOperation as operation, } from "./operations.js";
 import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, listRuns, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { ScheduleReferencesClient } from "./schedule-references-client.js";
 // Re-exported whole so `index.ts` and every existing importer keep their path.
 export * from "./client-config.js";
 import { browseQuery, createBrowseNamespace, } from "./client-browse.js";
@@ -12,16 +13,16 @@ import { createExplorationNamespace, } from "./client-exploration.js";
 import { createSourceMaterialCommentsNamespace, } from "./client-source-material-comments.js";
 import * as assoc from "./associations-client.js";
 import { brandColourDeck, brandProfile, listBrands } from "./brands-client.js";
+import { colourFacets as colourFacetsCall, resolveAttribute as resolveAttributeCall, resolveAttributeValue as resolveAttributeValueCall, resolveColour as resolveColourCall, suggest as suggestCall, suggestColour as suggestColourCall, } from "./client-vocabulary.js";
 import { CodesClient } from "./codes-client.js";
 import { ColoursClient } from "./colours-client.js";
 import { slotPools as slotPoolsCall, varyScheme as varySchemeCall, } from "./composition-client.js";
 import { coordinate as coordinateCall } from "./coordinate-client.js";
 import { matchStream as matchStreamCall } from "./match-stream.js";
-import { materialAssets as materialAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
+import { materialAssets as materialAssetsCall, materialRenderAssets as materialRenderAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
 import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
 import { resolvePhrasesRequest as resolvePhrases, searchVocabularyRequest, } from "./resolve-client.js";
 import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
-import { suggestQuery } from "./suggest-types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -58,6 +59,7 @@ import { suggestQuery } from "./suggest-types.js";
  * `./identifiers.ts`), absent is not false, and a page is not a corpus.
  */
 export class MaterialGraphClient extends CatalogueClient {
+    scheduleReferences;
     baseUrl;
     /**
      * THE QUESTION: "show me everything in this category / this brand, in a plain
@@ -121,6 +123,7 @@ export class MaterialGraphClient extends CatalogueClient {
         super(transport);
         this.#transport = transport;
         this.baseUrl = transport.baseUrl;
+        this.scheduleReferences = new ScheduleReferencesClient(transport);
         this.browse = createBrowseNamespace((params, signal) => this.#get("search_browse_by_colour", browseQuery(params), signal));
         this.codes = new CodesClient({
             get: (operationId, query, signal) => this.#get(operationId, query, signal),
@@ -143,10 +146,11 @@ export class MaterialGraphClient extends CatalogueClient {
             pathParams,
         });
     }
-    #post(operationId, body, signal) {
+    #post(operationId, body, signal, pathParams) {
         return this.#transport.requestJson(operation(operationId), {
             body,
             signal,
+            pathParams,
         });
     }
     /**
@@ -245,6 +249,8 @@ export class MaterialGraphClient extends CatalogueClient {
             category: params.category,
             brand: params.brand,
             family: params.family,
+            order: params.order,
+            maxColourDistance: params.maxColourDistance,
             corpusScope: params.corpusScope,
             limit: params.limit,
         }, signal);
@@ -282,6 +288,9 @@ export class MaterialGraphClient extends CatalogueClient {
     materialAssets(variantId, signal) {
         return materialAssetsCall(this.#transport, variantId, signal);
     }
+    materialRenderAssets(variantId, signal) {
+        return materialRenderAssetsCall(this.#transport, variantId, signal);
+    }
     materialDocuments(variantId, options, signal) {
         return materialDocumentsCall(this.#transport, variantId, options, signal);
     }
@@ -306,7 +315,7 @@ export class MaterialGraphClient extends CatalogueClient {
      *
      * READ `item.source` BEFORE PHRASING: the rail mixes three tiers of evidence —
      * `cospec` (real orders), `considered` (board activity), `colour` (palette
-     * look-alike). Only `cospec` supports "specified together". `cospecCount` tells
+     * look-alike). Only `cospec` supports "sampled together". `cospecCount` tells
      * you how much of the rail is real order evidence.
      */
     pairings(variantId, options, signal) {
@@ -314,6 +323,10 @@ export class MaterialGraphClient extends CatalogueClient {
             variantId,
         });
     }
+    /** Find bounded, exact-spec substitutes for one opaque variant id. */
+    findSubstitutes(variantId, options = {}, signal) {
+        return this.#post("find_material_substitutes", options, signal, { variantId });
+    }
     /** "What finishes does the manufacturer declare for THIS product?" — {@link declaredFinishes}. */
     associatedFinishes(variantId, options, signal) {
         return assoc.declaredFinishes(this.#transport, variantId, options, signal);
@@ -345,70 +358,30 @@ export class MaterialGraphClient extends CatalogueClient {
             idKind: options?.idKind ?? "variantId",
         }, signal);
     }
-    // ── Colour helpers ───────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "what colour WORDS may I use?" — family, mood and undertone
-     * with live counts. Vocabulary, not values: instead use `colours.profiles()`
-     * for a category's palette, {@link MaterialGraphClient.byColour} to search by a
-     * colour, {@link MaterialGraphClient.resolveColour} to turn a NAME into a hex.
-     */
+    /** Vocabulary families and counts; use `colours.profiles()` for a material palette. */
     colourFacets(signal) {
-        return this.#get("get_colour_facets", undefined, signal);
+        return colourFacetsCall(this.#transport, signal);
     }
-    /**
-     * THE QUESTION: "what hex is 'Hague Blue'?" — the step before
-     * {@link MaterialGraphClient.byColour} when you hold a name rather than a hex.
-     * A `null` match means unrecognised, not "no such colour".
-     */
+    /** Resolve a colour name to its canonical hex when recognised. */
     resolveColour(name, signal) {
-        return this.#get("resolve_colour_name", { name }, signal);
+        return resolveColourCall(this.#transport, name, signal);
     }
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
     suggestColour(q, options, signal) {
-        return this.#get("suggest_colour_names", { q, limit: options?.limit }, signal);
+        return suggestColourCall(this.#transport, q, options, signal);
     }
-    /**
-     * THE QUESTION: "what is the user starting to type?" It ranks NAMES, not
-     * materials — instead use {@link MaterialGraphClient.search} once they commit,
-     * {@link MaterialGraphClient.suggestColour} for colour names, and
-     * {@link MaterialGraphClient.searchVocabulary} for attribute/value tokens.
-     *
-     * Entity typeahead across products, brands and categories
-     * (GET `/api/v1/search/suggest`). Built for per-keystroke use: one indexed
-     * lookup, no embedding call and no model. Every suggestion carries the
-     * `refId` it resolves to — a product id, a brand slug, or a product-type key
-     * — so selecting one should navigate to that entity rather than re-running
-     * `label` as a search.
-     *
-     * @example
-     * const { suggestions } = await client.suggest("carr", { kind: "product" });
-     */
+    /** Entity typeahead. Navigate using the selected `refId`; use `search()` for materials. */
     suggest(q, options, signal) {
-        return this.#get("search_suggest", suggestQuery(q, options), signal);
+        return suggestCall(this.#transport, q, options, signal);
     }
     // ── Catalog ──────────────────────────────────────────────────────────────────
-    /**
-     * THE QUESTION: "the user said 'fire rating' — which canonical attribute is
-     * that?" Free text in, canonical `attributeId`s out; pair with
-     * {@link MaterialGraphClient.resolveAttributeValue} for the VALUE, then spend
-     * the pair on {@link MaterialGraphClient.bySpec} or `search({ filters })`.
-     * Instead use {@link MaterialGraphClient.specificationFacets} to browse rather
-     * than resolve.
-     */
+    /** Resolve free text to a canonical attribute id. */
     resolveAttribute(q, options, signal) {
-        return this.#get("catalog_resolve_attribute", { q, limit: options?.limit, facetableOnly: options?.facetableOnly }, signal);
+        return resolveAttributeCall(this.#transport, q, options, signal);
     }
-    /**
-     * THE QUESTION: "the user said 'class A' — what canonical term is that, under
-     * THIS attribute?" The value half of the pair
-     * {@link MaterialGraphClient.resolveAttribute} starts. Read
-     * `resolution.recommendedAction`, not just `best`: `ambiguous` means ask.
-     *
-     * @param attributeId Canonical vocabulary, not an opaque id — discover it, do
-     * not invent it.
-     */
+    /** Resolve a value under a canonical attribute id; inspect `recommendedAction` for ambiguity. */
     resolveAttributeValue(attributeId, query, options, signal) {
-        return this.#get("catalog_resolve_value", { q: query, limit: options?.limit }, signal, { attributeId });
+        return resolveAttributeValueCall(this.#transport, attributeId, query, options, signal);
     }
     /** "Is this phrase an attribute or a value?" — see {@link searchVocabularyRequest}. */
     searchVocabulary(query, options, signal) {
@@ -457,6 +430,14 @@ export class MaterialGraphClient extends CatalogueClient {
     taxonomy(signal) {
         return this.#get("get_category_taxonomy", undefined, signal);
     }
+    /**
+     * Exact current primary-type status counts by retained source category path.
+     * `comparisonThreshold` is a reporting cutoff only: it never promotes a
+     * proposal into an accepted category.
+     */
+    productTypeCoverage(options, signal) {
+        return this.#get("get_product_type_status_coverage", options, signal);
+    }
     /**
      * THE QUESTION: "what is this key allowed to do?" Check `scopes` before
      * offering a capability: the write surfaces need `mg:ingest` / `mg:compose`,
@@ -676,6 +657,10 @@ export class MaterialGraphClient extends CatalogueClient {
     runSchedule(runId, options) {
         return getRunSchedule(this.#transport, runId, options);
     }
+    /** Follow a verdict cell's citation handle to its canonical claim source. */
+    citation(citationId, signal) {
+        return this.#get("get_verdict_citation", undefined, signal, { citationId });
+    }
     /**
      * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
      *

package/composition-types.d.ts

@@ -12,6 +12,7 @@
  * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
  * so a new server value still type-checks; objects are read structurally.
  */
+import type { VerdictCitation } from "./citation-types.js";
 import type { RunId, SchemeId, SlotId, VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /**
@@ -158,6 +159,7 @@ export interface CompositionMatch {
     value?: string | null;
     /** Why an `unverified` cell missed the trust bar (MG-627), else null. */
     trustGap?: "below_confidence" | "basis_unmet" | "proposed" | null;
+    citation?: VerdictCitation;
 }
 /** One slot's chosen material plus the reason it was picked. */
 export interface CompositionPick {
@@ -303,6 +305,10 @@ export interface ReviewProgrammeSuspendPayload {
         element?: SlotElement;
         category?: string;
         categorySource?: SlotCategorySource;
+        /** Criteria grounding exhausted its one bounded retry; absent otherwise. */
+        groundingFailure?: {
+            reason: "criteria-resolution-failed";
+        };
         provenance: ProgrammeProvenance;
     }>;
     /**

package/corpus-scope-types.d.ts

@@ -43,7 +43,7 @@ import { type OpenEnum } from "./types.js";
  * that were never in the Material Bank feed; if you mean orderable, use one of
  * the channel-backed scopes above.
  */
-export type CorpusScope = OpenEnum<"all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaAndCatalogue" | "materialBankNaOrderable" | "materialBankOrderable">;
+export type CorpusScope = OpenEnum<"samplizeCatalogue" | "all" | "designShopOrderable" | "materialBankEuOrderable" | "materialBankNaAndCatalogue" | "materialBankNaOrderable" | "materialBankOrderable">;
 /**
  * The corpus a response AND its counts were drawn from. Present only when a
  * narrowing scope applied — absence means the whole graph. Read it alongside

package/errors.d.ts

@@ -89,7 +89,7 @@ interface TransportErrorInput extends MaterialGraphRequestMetadata {
  * 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 ["content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "orderable_attributes", "populated_alternatives", "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", "unknown_attributes", "unknown_brands", "unknown_fields", "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

@@ -23,6 +23,8 @@ const RETRIABLE_STATUS = new Set([502, 503, 504]);
  * `problem-extension-parity.test.ts` fails when the two disagree.
  */
 export const MATERIALGRAPH_PROBLEM_EXTENSIONS = [
+    "ambiguous_brands",
+    "brand_candidates",
     "content_length",
     "did_you_mean",
     "empty_brands",

package/index.d.ts

@@ -7,6 +7,7 @@ export type * from "./exploration-types.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type * from "./run-types.js";
 export type * from "./schedule-types.js";
+export type * from "./citation-types.js";
 export { VARY_AXES } from "./composition-types.js";
 export type * from "./composition-types.js";
 export type * from "./slot-pool-types.js";
@@ -36,10 +37,15 @@ export type * from "./association-types.js";
 export type * from "./brand-types.js";
 export type * from "./fan-deck-types.js";
 export type * from "./material-asset-types.js";
+export type * from "./render-assets-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 "./schedule-reference-types.js";
+export type * from "./substitute-types.js";
 export type * from "./search-refinement-types.js";
 export type * from "./search-window-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export type * from "./spec-types.js";
 export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";
+export type { SamplizePublicationSource, SamplizeLrvObservation, SamplizeDemand, SamplizeCollectionMembership, SamplizeCatalogueOptions, SamplizeCataloguePage, SamplizeCatalogueProduct, SamplizeHexObservation, } from "./samplize-catalogue-types.js";

package/json-value-types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A JSON value, recursively — exactly what survives a `jsonb` round-trip
+ * unchanged. Used where a payload's SHAPE belongs to its producer but its values
+ * must still be JSON: `Date`, `bigint`, `undefined`, and functions are not.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};

package/json-value-types.js

@@ -0,0 +1 @@
+export {};

package/match-types.d.ts

@@ -1,3 +1,4 @@
+import type { CorpusScope } from "./corpus-scope-types.js";
 /**
  * @module sdk/match-types
  * @description The buffered Material Match request and response, hand-mirrored
@@ -92,6 +93,8 @@ export interface MatchInput {
      */
     includeBelowFloor?: boolean;
     requestedType?: OpenEnum<"swatch" | "installation" | "flatplan">;
+    /** Corpus to retrieve candidates from, applied inside retrieval. */
+    corpusScope?: CorpusScope;
     /** Hard spec gates forwarded verbatim to the inner search — term match or presence, each with an optional trust bar. */
     filters?: SearchFilter[];
     /** Soft criteria (rank-never-exclude). A miss demotes within the page but never removes a hit. */

package/material-resources-client.d.ts

@@ -3,10 +3,13 @@ import { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 import type { MaterialAssetProjection, MaterialDocumentPage, MaterialDocumentPageOptions } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
+import type { MaterialRenderAssets } from "./render-assets-types.js";
 /** Read known and explicitly unobserved canonical material fields. */
 export declare function materialBlocks(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialBlockProjection>;
 /** Read only redistribution-safe images and downloads for a material. */
 export declare function materialAssets(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialAssetProjection>;
+/** Read the accepted render-ready appearance projection, or an explicit unavailable reason. */
+export declare function materialRenderAssets(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialRenderAssets>;
 /**
  * Read the owning Product's URL-deduplicated document page. Variant declarations
  * retain exact attribution; consumers inspect `appliesToRequestedVariant`

package/material-resources-client.js

@@ -9,6 +9,10 @@ export function materialBlocks(transport, variantId, signal) {
 export function materialAssets(transport, variantId, signal) {
     return transport.requestJson(resolveOperation("list_material_assets"), { signal, pathParams: { variantId } });
 }
+/** Read the accepted render-ready appearance projection, or an explicit unavailable reason. */
+export function materialRenderAssets(transport, variantId, signal) {
+    return transport.requestJson(resolveOperation("get_material_render_assets"), { signal, pathParams: { variantId } });
+}
 /**
  * Read the owning Product's URL-deduplicated document page. Variant declarations
  * retain exact attribution; consumers inspect `appliesToRequestedVariant`

package/material-types.d.ts

@@ -57,6 +57,8 @@ export interface MaterialSuccessor {
  * successor record — read the detail projection for that.
  */
 export interface MaterialTile {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
     /** Opaque — round-trip verbatim into every other material read. */
     variantId: VariantId;
     brand: string;
@@ -87,6 +89,27 @@ export interface MaterialTile {
 export interface MaterialFacet {
     attributeId: string;
     term: string;
+    /**
+     * Whether this value identifies the variant or specifies its performance /
+     * composition. Present on current responses; optional for captured older
+     * payloads. Only `specification` facets are valid inputs to `bySpec`.
+     */
+    role?: "identity" | "specification";
+}
+/** A retained product-type proposal. It is review evidence, never a category. */
+export interface ProposedProductType {
+    id: string;
+    displayName: string;
+    confidence: number | null;
+    /** Canonical source URL when the proposal retained one; null when it did not. */
+    sourceUrl: string | null;
+    isPrimary: boolean;
+    scope: "variant" | "product";
+}
+/** Accepted display categories remain separate from this review-state receipt. */
+export interface ProductTypeReceipt {
+    state: "accepted" | "proposed" | "unknown";
+    proposedProductTypes: ProposedProductType[];
 }
 /**
  * One dimensional configuration of a material. Numeric fields are millimetres
@@ -132,6 +155,7 @@ export interface MaterialDetail extends MaterialTile {
     sourceStatus?: "provisional";
     installationImageUrl: string | null;
     displayCategory: string | null;
+    productTypeReceipt: ProductTypeReceipt;
     categoryPath: string[];
     /** Durable state of image-colour extraction and its variant projection. */
     colourEvidence: {

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.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 ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], 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 ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["exploration.operators", "GET", "/api/v1/materials/{variantId}/operators", "list_material_operators"], readonly ["exploration.candidates", "POST", "/api/v1/materials/{variantId}/candidates", "read_material_candidates"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], 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 ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["brandColourDeck", "GET", "/api/v1/brands/{brandSlug}/colours", "brand_colour_deck"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["sourceMaterialComments", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments", "POST", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "post_source_material_comment"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["listRuns", "GET", "/api/v1/runs", "list_public_runs"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["scheduleReferences.list", "GET", "/api/v1/schedules/{scheduleId}/references", "list_schedule_reference_feedback"], readonly ["scheduleReferences.put", "PUT", "/api/v1/schedules/{scheduleId}/references/{referenceId}", "put_schedule_reference_feedback"], 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 ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], 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 ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["materialRenderAssets", "GET", "/api/v1/materials/{variantId}/render-assets", "get_material_render_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["exploration.operators", "GET", "/api/v1/materials/{variantId}/operators", "list_material_operators"], readonly ["exploration.candidates", "POST", "/api/v1/materials/{variantId}/candidates", "read_material_candidates"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["findSubstitutes", "POST", "/api/v1/materials/{variantId}/substitutes", "find_material_substitutes"], 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 ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["productTypeCoverage", "GET", "/api/v1/taxonomy/coverage", "get_product_type_status_coverage"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["brandColourDeck", "GET", "/api/v1/brands/{brandSlug}/colours", "brand_colour_deck"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["sourceMaterialComments", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments", "POST", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "post_source_material_comment"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["listRuns", "GET", "/api/v1/runs", "list_public_runs"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -1,6 +1,18 @@
 import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
+    [
+        "scheduleReferences.list",
+        "GET",
+        "/api/v1/schedules/{scheduleId}/references",
+        "list_schedule_reference_feedback",
+    ],
+    [
+        "scheduleReferences.put",
+        "PUT",
+        "/api/v1/schedules/{scheduleId}/references/{referenceId}",
+        "put_schedule_reference_feedback",
+    ],
     ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
     [
         "catalogPages",
@@ -22,6 +34,12 @@ const OPERATION_DEFINITIONS = [
     ],
     ["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"],
     ["match", "POST", "/api/v1/search/match", "match_material"],
     ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"],
@@ -62,6 +80,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/materials/{variantId}/assets",
         "list_material_assets",
     ],
+    [
+        "materialRenderAssets",
+        "GET",
+        "/api/v1/materials/{variantId}/render-assets",
+        "get_material_render_assets",
+    ],
     [
         "materialDocuments",
         "GET",
@@ -115,6 +139,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/materials/{variantId}/pairings",
         "get_material_pairings",
     ],
+    [
+        "findSubstitutes",
+        "POST",
+        "/api/v1/materials/{variantId}/substitutes",
+        "find_material_substitutes",
+    ],
     [
         "associatedFinishes",
         "GET",
@@ -178,6 +208,12 @@ const OPERATION_DEFINITIONS = [
     ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"],
     ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"],
     ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"],
+    [
+        "productTypeCoverage",
+        "GET",
+        "/api/v1/taxonomy/coverage",
+        "get_product_type_status_coverage",
+    ],
     ["whoami", "GET", "/api/v1/whoami", "whoami"],
     ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"],
     ["demand", "GET", "/api/v1/demand", "get_material_demand"],
@@ -255,6 +291,7 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/runs/{runId}/schedule",
         "get_run_finish_schedule",
     ],
+    ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"],
     [
         "streamRunEvents",
         "GET",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "exports": {
     ".": {

package/palette-search-types.d.ts

@@ -1,3 +1,4 @@
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 /**
  * Wire types for MULTI-COLOUR search — `POST /api/v1/search/palettes` and
  * `POST /api/v1/search/gradients`.
@@ -34,6 +35,7 @@ export interface GradientStop {
     oklab?: OklabTriple;
 }
 export interface SearchPaletteInput {
+    corpusScope?: CorpusScope;
     /** The palette to match, 1–8 colours. */
     colours: PaletteQueryColour[];
     /**
@@ -46,14 +48,15 @@ export interface SearchPaletteInput {
     limit?: number;
 }
 export interface SearchGradientInput {
+    corpusScope?: CorpusScope;
     /** The ordered colour transition, 2–6 stops. */
     stops: GradientStop[];
     /** Results to return; defaults to 24, capped at 48. */
     limit?: number;
 }
 /**
- * One swatch of a candidate's colorscope-EXTRACTED palette. Derived from product
- * imagery, never a manufacturer's declared colour. `name` is null when no human
+ * One swatch used for scoring. Samplize paint uses its selected published hex;
+ * other materials use colorscope palettes extracted from imagery. `name` is null when no human
  * name was resolved — unnamed, not colourless.
  */
 export interface CandidateSwatch {
@@ -140,14 +143,24 @@ export interface HueGateReceipt {
  * materials match this palette" is not a claim you can make from it.
  */
 export interface SearchPaletteResponse {
+    corpusScope?: CorpusScopeReceipt;
     /** The query as interpreted — check it before trusting a surprising order. */
     query: {
+        /** Colours that actually ran after minor stated shares were omitted. */
         colours: Array<{
             hex: string;
             proportion?: number;
             weight?: number;
         }>;
+        /** Colours not searched because their stated share was below 5%. */
+        droppedColours: Array<{
+            hex: string;
+            proportion?: number;
+            weight?: number;
+        }>;
         logic: PaletteLogic;
+        /** `no_effective_colours` means no material query ran. */
+        outcome: OpenEnum<"matches" | "no_effective_colours">;
     };
     /** The hue-family admission gate this page was scored under. */
     hueGate: HueGateReceipt;
@@ -157,6 +170,7 @@ export interface SearchPaletteResponse {
 }
 /** A PAGE, NOT A CORPUS — see {@link SearchPaletteResponse}. */
 export interface SearchGradientResponse {
+    corpusScope?: CorpusScopeReceipt;
     query: {
         stops: string[];
         /** The sampled path points the search actually ran against. */