@instruments/materialgraph 0.10.0 → 0.11.0

package/colour-aggregate-types.d.ts

@@ -88,6 +88,43 @@ export interface ColourStatsGroup {
     productTypes: number;
     variants: number;
 }
+/**
+ * One cell of the brand x category x colour-family matrix — the shape that
+ * answers questions no single dimension can, such as "how many whites does
+ * Benjamin Moore offer in paint".
+ */
+export interface ColourStatsRow {
+    /** Opaque brand id — the join key for brand reads. Never parse it. */
+    brandId: string;
+    brandSlug: string;
+    brandName: string;
+    /**
+     * Product-type key. NULL means these variants carry NO accepted primary
+     * product type — a real population, kept so the matrix sums to the corpus,
+     * not an error and not a residual bucket.
+     */
+    categoryKey: string | null;
+    family: string;
+    /**
+     * Distinct variants at this (brand, category, family) carrying an ACCEPTED
+     * `colour_family`. Not every variant of the brand.
+     */
+    variants: number;
+}
+/** How to narrow the matrix. Passing ANY of these asks for `rows`. */
+export interface ColourStatsParams {
+    /** `"brand,category"` — ask for the whole matrix, unscoped. */
+    groupBy?: string;
+    brandId?: string;
+    brandSlug?: string;
+    /**
+     * A product-type key, or the literal `"null"` for the unclassified
+     * population. Omitting it means every category — a different question.
+     */
+    categoryKey?: string;
+    family?: string;
+    limit?: number;
+}
 /** Where each section came from, how fresh it is, and what it does NOT answer. */
 export interface ColourStatsBasis {
     corpus: string;
@@ -95,11 +132,32 @@ export interface ColourStatsBasis {
     groups: string;
     groupsRefreshedAt: string | null;
     groupsVariantCount: number;
+    /**
+     * Where `rows` came from, its freshness, and what it EXCLUDES — present only
+     * when `rows` is. Read it: the matrix deliberately omits Samplize, which is a
+     * sampling channel printing other manufacturers' colours rather than a maker.
+     */
+    rows?: string;
     omissions: string[];
 }
 export interface ColourStatsResponse {
     corpus: ColourStatsCorpus;
     families: ColourStatsFamily[];
     groups: ColourStatsGroup[];
+    /**
+     * The brand x category x colour-family matrix. Present ONLY when you asked
+     * for it; ABSENT means nobody asked, never that the matrix is empty.
+     *
+     * `families` above is NOT scoped by the same parameters and stays
+     * platform-wide under all of them. Scoped counts live here.
+     */
+    rows?: ColourStatsRow[];
+    /**
+     * Rows matching your query BEFORE the response cap — the honest total.
+     * A shortfall against `rows.length` means `rows` is a prefix.
+     */
+    rowsMatched?: number;
+    /** TRUE when the matrix exceeded the cap and `rows` is a prefix. */
+    rowsTruncated?: boolean;
     basis: ColourStatsBasis;
 }

package/colours-client.d.ts

@@ -32,7 +32,7 @@
  * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
  * likeness, never a stated colour specification.
  */
-import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsResponse } from "./colour-aggregate-types.js";
+import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsParams, ColourStatsResponse } from "./colour-aggregate-types.js";
 import type { QueryParams } from "./http-transport.js";
 import type { SdkOperationId } from "./operations.js";
 import type { SearchGradientInput, SearchGradientResponse, SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
@@ -87,8 +87,14 @@ export declare class ColoursClient {
      * coverage per product-type group. `basis` states the source and freshness of
      * each section plus `basis.omissions` — what this call deliberately does not
      * answer, listed rather than silently absent.
+     *
+     * Pass `{ groupBy: "brand,category" }` for the whole brand x category x
+     * family matrix in one call, or a `brandSlug`/`categoryKey` scope for a slice
+     * of it — either way it arrives as `rows`, each row carrying `brandId` and
+     * `brandSlug` to join on. Without any of those parameters the payload is the
+     * platform-wide one and `rows` is absent. `families` is never scoped by them.
      */
-    stats(signal?: AbortSignal): Promise<ColourStatsResponse>;
+    stats(params?: ColourStatsParams, signal?: AbortSignal): Promise<ColourStatsResponse>;
     /**
      * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at
      * stated proportions, not one colour repeated (POST `/api/v1/search/palettes`).

package/colours-client.js

@@ -53,9 +53,22 @@ export class ColoursClient {
      * coverage per product-type group. `basis` states the source and freshness of
      * each section plus `basis.omissions` — what this call deliberately does not
      * answer, listed rather than silently absent.
+     *
+     * Pass `{ groupBy: "brand,category" }` for the whole brand x category x
+     * family matrix in one call, or a `brandSlug`/`categoryKey` scope for a slice
+     * of it — either way it arrives as `rows`, each row carrying `brandId` and
+     * `brandSlug` to join on. Without any of those parameters the payload is the
+     * platform-wide one and `rows` is absent. `families` is never scoped by them.
      */
-    stats(signal) {
-        return this.#transport.get("get_colour_stats", undefined, signal);
+    stats(params = {}, signal) {
+        return this.#transport.get("get_colour_stats", {
+            groupBy: params.groupBy,
+            brandId: params.brandId,
+            brandSlug: params.brandSlug,
+            categoryKey: params.categoryKey,
+            family: params.family,
+            limit: params.limit,
+        }, signal);
     }
     /**
      * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at

package/composition-client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The COMPOSITION lens: the two synchronous scheme surfaces, as thin wrappers
+ * over the shared {@link HttpTransport}. `MaterialGraphClient.varyScheme` and
+ * `.slotPools` delegate here; the contract lives in this file.
+ *
+ * They are two altitudes of the same capability. `varyScheme` re-derives a
+ * scheme MaterialGraph itself composed; `slotPools` hands the ranked candidates
+ * to a composer that is not MaterialGraph, and keeps none of the ownership.
+ */
+import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.js";
+import { HttpTransport } from "./http-transport.js";
+import type { SlotPoolsRequest, SlotPoolsResponse } from "./slot-pool-types.js";
+/**
+ * THE QUESTION: "show me the same brief, decided differently." Re-derives an
+ * option B from a succeeded compose Run along ONE constraint axis. Deterministic
+ * and synchronous — the response IS the hydrated scheme (no Run envelope),
+ * stamped with axis + source provenance whose `notes` are the receipts.
+ * Requires the `mg:read` scope.
+ */
+export declare function varyScheme(transport: HttpTransport, body: VarySchemesRequest, signal?: AbortSignal): Promise<VarySchemesResponse>;
+/**
+ * THE QUESTION: "for each of these slots, what should I be choosing between?"
+ * Up to 24 self-contained tasks in, one ranked and gated candidate pool each
+ * out, correlated by YOUR `taskKey`. Synchronous, uncached and project-free —
+ * no Run, no programme, no state kept on the MaterialGraph side.
+ *
+ * READ THE POOLS, NOT JUST THE CANDIDATES. A task whose search failed comes back
+ * with a `search-failed` shortfall while the rest answer normally; a candidate
+ * with `eligible: false` is LABELLED rather than dropped (read `flags`); and a
+ * criterion that graded `missing` or `not_evaluated` was never a failure.
+ * Requires the `mg:read` scope.
+ */
+export declare function slotPools(transport: HttpTransport, body: SlotPoolsRequest, signal?: AbortSignal): Promise<SlotPoolsResponse>;

package/composition-client.js

@@ -0,0 +1,27 @@
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "show me the same brief, decided differently." Re-derives an
+ * option B from a succeeded compose Run along ONE constraint axis. Deterministic
+ * and synchronous — the response IS the hydrated scheme (no Run envelope),
+ * stamped with axis + source provenance whose `notes` are the receipts.
+ * Requires the `mg:read` scope.
+ */
+export function varyScheme(transport, body, signal) {
+    return transport.requestJson(resolveOperation("vary_schemes"), { body, signal });
+}
+/**
+ * THE QUESTION: "for each of these slots, what should I be choosing between?"
+ * Up to 24 self-contained tasks in, one ranked and gated candidate pool each
+ * out, correlated by YOUR `taskKey`. Synchronous, uncached and project-free —
+ * no Run, no programme, no state kept on the MaterialGraph side.
+ *
+ * READ THE POOLS, NOT JUST THE CANDIDATES. A task whose search failed comes back
+ * with a `search-failed` shortfall while the rest answer normally; a candidate
+ * with `eligible: false` is LABELLED rather than dropped (read `flags`); and a
+ * criterion that graded `missing` or `not_evaluated` was never a failure.
+ * Requires the `mg:read` scope.
+ */
+export function slotPools(transport, body, signal) {
+    return transport.requestJson(resolveOperation("slot_pools"), { body, signal });
+}

package/composition-types.d.ts

@@ -284,6 +284,34 @@ export interface ReviewProgrammeSuspendPayload {
         categorySource?: SlotCategorySource;
         provenance: ProgrammeProvenance;
     }>;
+    /**
+     * Lines this room usually carries that the brief never named.
+     *
+     * Offered, never imposed: a programme that proceeds without them is a legal
+     * answer. `essential` marks the ones whose absence makes the room unbuildable
+     * as specified; `ffe` marks furniture and lighting the catalogue does not
+     * serve yet, carried because a bedroom with no bed on the schedule is a gap
+     * worth seeing coming. Add one with an `add-slot` correction.
+     */
+    unstated?: Array<{
+        spaceId: string;
+        key: string;
+        name: string;
+        element: SlotElement;
+        /**
+         * Absent and `null` both mean the graph has no category for this line, and a
+         * reader must treat them as one answer.
+         *
+         * The distinction does not survive the wire. A `null` set server-side
+         * arrives as an absent key on the far side of the workflow runtime, so a
+         * client that branched on which one it received would be reading transport
+         * noise as meaning. An FF&E line the catalogue does not serve — a table
+         * lamp, bed linen, ironmongery — has no category under either reading.
+         */
+        category?: string | null;
+        weight: "essential" | "optional";
+        ffe?: boolean;
+    }>;
 }
 /**
  * Resume grammar for the `review-programme` step: drop a slot, drop a space
@@ -310,6 +338,24 @@ export interface ReviewProgrammeResumeData {
         action: "set-slot-category";
         slotId: string;
         category: string;
+    }
+    /**
+     * ADD a line the brief never named — usually one the payload offered under
+     * `unstated`, though any line is legal. Every other verb here subtracts,
+     * which made the programme a ceiling: whatever the brief happened to
+     * mention was the most a schedule could ever contain.
+     *
+     * `category` may be null or absent, because some real lines — grout,
+     * ironmongery, sanitaryware — have no catalog category yet. Such a slot is
+     * skipped at retrieval with a counted `no-category` shortfall, which is the
+     * honest treatment of a line we can hold but not yet fill.
+     */
+     | {
+        action: "add-slot";
+        spaceId: string;
+        name: string;
+        element: SlotElement;
+        category?: string | null;
     }>;
 }
 /**

package/coordinate-client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The COORDINATION lens: given several materials already chosen, what completes
+ * them. A thin wrapper over the shared {@link HttpTransport};
+ * `MaterialGraphClient.coordinate` delegates here.
+ *
+ * Extracted from `client.ts`, which sits above the repository's source-size
+ * limit, in the same per-lens shape as `brands-client` / `codes-client` /
+ * `colours-client`. Behaviour is unchanged.
+ */
+import { HttpTransport } from "./http-transport.js";
+import type { CoordinateInput, CoordinateResponse } from "./types.js";
+/**
+ * THE QUESTION: "here is my whole scheme so far — what completes it?" The
+ * multi-seed form of `pairings`: lift is SUMMED across seeds, so a companion
+ * suiting one pick ranks below one suiting several. Returns demand-lift-ranked
+ * companions with colour swatches and an annotate-only `colourFit` that never
+ * reorders in v1.
+ *
+ * Instead use `pairings` for a single material, and `colours.palette()` when the
+ * scheme is COLOURS rather than materials. Check `unresolved` before presenting:
+ * a reference that resolved to nothing is named there, not dropped.
+ */
+export declare function coordinate(transport: HttpTransport, input: CoordinateInput, signal?: AbortSignal): Promise<CoordinateResponse>;

package/coordinate-client.js

@@ -0,0 +1,25 @@
+/**
+ * The COORDINATION lens: given several materials already chosen, what completes
+ * them. A thin wrapper over the shared {@link HttpTransport};
+ * `MaterialGraphClient.coordinate` delegates here.
+ *
+ * Extracted from `client.ts`, which sits above the repository's source-size
+ * limit, in the same per-lens shape as `brands-client` / `codes-client` /
+ * `colours-client`. Behaviour is unchanged.
+ */
+import { HttpTransport } from "./http-transport.js";
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "here is my whole scheme so far — what completes it?" The
+ * multi-seed form of `pairings`: lift is SUMMED across seeds, so a companion
+ * suiting one pick ranks below one suiting several. Returns demand-lift-ranked
+ * companions with colour swatches and an annotate-only `colourFit` that never
+ * reorders in v1.
+ *
+ * Instead use `pairings` for a single material, and `colours.palette()` when the
+ * scheme is COLOURS rather than materials. Check `unresolved` before presenting:
+ * a reference that resolved to nothing is named there, not dropped.
+ */
+export function coordinate(transport, input, signal) {
+    return transport.requestJson(resolveOperation("coordinate_materials"), { body: input, signal });
+}

package/exploration-types.d.ts

@@ -0,0 +1,110 @@
+import type { VariantId } from "./identifiers.js";
+export type GraphOperator = "colourways" | "same_category" | "still_listed" | "looks_like" | "same_colour" | "pairs_with" | "often_specified_with" | "substitutes_for" | "more_durable" | "outdoor_suitable" | "lower_cost" | "more_sustainable";
+export interface GraphOperatorAvailability {
+    operator: GraphOperator;
+    operatorClass: "identity" | "perceptual" | "relational" | "spec";
+    label: string;
+    available: boolean;
+    basis: string;
+    count?: number;
+}
+export interface GraphOperatorEvidence {
+    variantId: VariantId;
+    operators: GraphOperatorAvailability[];
+}
+export interface CandidateReadInput {
+    operator: "looks_like";
+    corpusScope?: "all" | "materialBankOrderable";
+    limit?: number;
+    excludeVariantIds?: VariantId[];
+}
+export interface CandidateReadImage {
+    url: string;
+    source: "r2" | "origin";
+    /** Null means this image has not been analysed for a uniform light background. */
+    isIsolated: boolean | null;
+}
+export interface CandidateReadPaletteSwatch {
+    hex: string;
+    proportion: number;
+    name?: string | null;
+}
+export interface CandidateReadCard {
+    variantId: VariantId;
+    productId: string;
+    brandSlug: string;
+    materialBankId: string | null;
+    brand: string;
+    product: string;
+    variantName: string | null;
+    color: string | null;
+    image: CandidateReadImage | null;
+    palette: CandidateReadPaletteSwatch[];
+}
+export interface CandidateRankEvidence {
+    rank: number;
+    distance: number;
+    similarity: number;
+    basis: "active_main_image_embedding";
+    provenanceGrade: "measured";
+    displayImageMatchedEvidence: boolean | null;
+}
+export interface CandidateReadCandidate extends CandidateReadCard {
+    evidence: CandidateRankEvidence;
+    reason: string;
+}
+export interface CandidateSeedEvidence {
+    evidenceImageSha256: string;
+    displayImageSha256: string | null;
+    basis: "active_main_image_embedding";
+    provenanceGrade: "measured";
+    displayImageMatchedEvidence: boolean | null;
+}
+export interface CandidateReadReceipt {
+    operator: "looks_like";
+    corpusScope: {
+        scope: "all" | "materialBankOrderable";
+        description: string;
+    } | null;
+    requestedLimit: number;
+    returnedCount: number;
+    exclusions: {
+        requested: number;
+        unique: number;
+        applied: number;
+    };
+    dedupe: {
+        retrieved: number;
+        removed: number;
+        truncated: number;
+        projectionMisses: number;
+    };
+    timing: {
+        /** Internal seed projection completion; not a consumer response milestone. */
+        seedProjectionMs: number;
+        retrievalMs: number;
+        projectionMs: number;
+        completeMs: number;
+    };
+}
+interface CandidateReadResponseBase {
+    seed: CandidateReadCard;
+    receipt: CandidateReadReceipt;
+}
+export type CandidateReadResponse = (CandidateReadResponseBase & {
+    status: "ready";
+    seedEvidence: CandidateSeedEvidence;
+    candidates: CandidateReadCandidate[];
+    reason: null;
+}) | (CandidateReadResponseBase & {
+    status: "no_candidates" | "no_unseen_candidates" | "bounded_retrieval_unavailable";
+    seedEvidence: CandidateSeedEvidence;
+    candidates: [];
+    reason: string;
+}) | (CandidateReadResponseBase & {
+    status: "operator_unavailable";
+    seedEvidence: null;
+    candidates: [];
+    reason: string;
+});
+export {};

package/exploration-types.js

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

package/fan-deck-types.d.ts

@@ -26,7 +26,10 @@ export interface FanDeckFamily {
     count: number;
 }
 export interface BrandFanDeck {
-    /** The brands the deck covers, as resolved from the slug. */
+    /**
+     * The brand SLUGS the deck resolved to — round-trippable identifiers, not
+     * display names. The maker's name as it should be shown is on every swatch.
+     */
     brands: string[];
     /** Grouped by `families` order, light to dark within each family. */
     swatches: FanDeckSwatch[];

package/index.d.ts

@@ -1,13 +1,15 @@
 export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
-export type { MaterialGraphClientOptions, BrowseNamespace } from "./client.js";
+export type { MaterialGraphClientOptions, BrowseNamespace, ExplorationNamespace, SourceMaterialCommentsNamespace, } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
 export type * from "./identifiers.js";
+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 { VARY_AXES } from "./composition-types.js";
 export type * from "./composition-types.js";
+export type * from "./slot-pool-types.js";
 export { PROJECT_EVENT_KINDS } from "./project-types.js";
 export type * from "./project-types.js";
 export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
@@ -16,6 +18,7 @@ export { MaterialGraphError } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
 export type * from "./match-types.js";
+export type * from "./browse-types.js";
 export type * from "./by-colour-types.js";
 export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 export type * from "./match-stream-types.js";

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], 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 ["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 ["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 ["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 ["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 ["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 ["search", "POST", "/api/v1/search", "search_materials_post"], 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 ["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 ["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 ["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"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -24,6 +24,18 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/materials/{variantId}/assets",
         "list_material_assets",
     ],
+    [
+        "exploration.operators",
+        "GET",
+        "/api/v1/materials/{variantId}/operators",
+        "list_material_operators",
+    ],
+    [
+        "exploration.candidates",
+        "POST",
+        "/api/v1/materials/{variantId}/candidates",
+        "read_material_candidates",
+    ],
     ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"],
     ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"],
     ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"],
@@ -176,6 +188,18 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/source-material/{batchId}",
         "get_source_material_batch",
     ],
+    [
+        "sourceMaterialComments",
+        "GET",
+        "/api/v1/source-material/{batchId}/sources/{sourceId}/comments",
+        "list_source_material_comments",
+    ],
+    [
+        "sourceMaterialComments",
+        "POST",
+        "/api/v1/source-material/{batchId}/sources/{sourceId}/comments",
+        "post_source_material_comment",
+    ],
     ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"],
     ["createRun", "POST", "/api/v1/runs", "create_public_run"],
     ["listRuns", "GET", "/api/v1/runs", "list_public_runs"],
@@ -195,6 +219,7 @@ const OPERATION_DEFINITIONS = [
     ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"],
     ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"],
     ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"],
+    ["slotPools", "POST", "/api/v1/schemes/pools", "slot_pools"],
     ["createProject", "POST", "/api/v1/projects", "create_box_project"],
     ["listProjects", "GET", "/api/v1/projects", "list_box_projects"],
     ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"],

package/package.json

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

package/palette-search-types.d.ts

@@ -86,6 +86,18 @@ export interface MultiColourMatchBase {
     imageUrl: string | null;
     /** MB has retired or hidden this SKU. */
     retired: boolean;
+    /**
+     * The catalog GROUP — "Flooring", "Textile Materials", "Coatings" — or null
+     * when the material has no accepted primary product type.
+     *
+     * A palette query is cross-category BY INTENT: a designer building a scheme,
+     * not browsing one aisle. So this is the field that says whether a result
+     * answers the question — one real palette returned 30 of 40 results in a
+     * single category while every one of the fourteen groups held something
+     * closer on the same colours (MG-1245). Group by it, and keep null as its own
+     * bucket: null means UNKNOWN, not uncategorised, and it is not rare.
+     */
+    category: string | null;
     /** The candidate's full extracted palette — the evidence scored against. */
     palette: CandidateSwatch[];
     /** The aggregate match score in [0,1]; higher is closer. */
@@ -105,6 +117,23 @@ export interface GradientMatch extends MultiColourMatchBase {
     /** One receipt per sampled point along the path, in path order. */
     samples: ColourMatchReceipt[];
 }
+/**
+ * The hue-family ADMISSION gate the page was scored under: a candidate swatch
+ * may satisfy a query colour only if colorscope's `isHueCompatible` admits it
+ * at these exact thresholds. A refused swatch is absent from that colour's
+ * matching entirely — it did not merely rank low. Admission, not ranking: it
+ * decides which swatches count, never their order. Server-side and fixed (no
+ * request knob); the receipt exists so a threshold change is visible on the
+ * wire.
+ */
+export interface HueGateReceipt {
+    /** Below this query chroma the colour is achromatic and any hue is admitted. */
+    achromaticQueryChroma: number;
+    /** A swatch must carry at least this share of the query colour's chroma. */
+    minChromaRatio: number;
+    /** Floor on the cosine agreement between the two hue vectors. */
+    minHueCosine: number;
+}
 /**
  * A PAGE, NOT A CORPUS. `count` is `matches.length` under `limit` (24 default,
  * 48 max) — this surface states no corpus total and has no cursor, so "N
@@ -120,6 +149,8 @@ export interface SearchPaletteResponse {
         }>;
         logic: PaletteLogic;
     };
+    /** The hue-family admission gate this page was scored under. */
+    hueGate: HueGateReceipt;
     /** `matches.length`, capped by `limit`. Never a corpus total. */
     count: number;
     matches: PaletteMatch[];