@instruments/materialgraph 0.20.0 → 0.22.0

package/brand-most-sampled-types.d.ts

@@ -0,0 +1,33 @@
+import type { CandidateReadCard } from "./exploration-types.js";
+export interface BrandMostSampledResponse {
+    data: {
+        brand: {
+            id: string;
+            name: string;
+        };
+        status: "ready" | "unavailable";
+        metric: "sample_order_lines";
+        provenance: {
+            source: "material_bank_order_history";
+            signal: "sampled";
+            sessionId: string;
+            window: "trailing_36mo";
+            windowStart: string;
+            windowEnd: string;
+        } | null;
+        products: Array<{
+            rank: number;
+            sampleOrderLines: number;
+            representativeVariantSampleOrderLines: number;
+            card: CandidateReadCard & {
+                category: string | null;
+            };
+        }>;
+    };
+    meta: {
+        operationId: "brands.most_sampled";
+        requestId: string;
+    };
+    links: Record<string, never>;
+    warnings: never[];
+}

package/brand-most-sampled-types.js

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

package/catalogue-client.d.ts

@@ -1,4 +1,7 @@
+import type { BrandMostSampledResponse } from "./brand-most-sampled-types.js";
 import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueCollectionsOptions, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
+import type { CompareInput, CompareResponse } from "./compare-types.js";
+import type { CreateCorrectionInput, CorrectionResponse, CorrectionsListResponse } from "./correction-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 import type { IdentifySelectedPageInput, IdentifySelectedPageResult } from "./identify-types.js";
@@ -8,6 +11,22 @@ import type { SamplizeColorVecCache } from "./samplize-colorvec.js";
 export declare class CatalogueClient {
     #private;
     protected constructor(transport: HttpTransport);
+    /** Brand products ranked by observed Material Bank sample-order lines, with window provenance. */
+    brandMostSampled(brandId: string, options?: {
+        limit?: number;
+    }, signal?: AbortSignal): Promise<BrandMostSampledResponse>;
+    /** Compare canonical Variants without searching or ranking them. */
+    compare(input: CompareInput, signal?: AbortSignal): Promise<CompareResponse>;
+    /** Submit confirmed caller-authored review work; never changes accepted truth. */
+    createCorrection(input: CreateCorrectionInput, options: {
+        idempotencyKey: string;
+        signal?: AbortSignal;
+    }): Promise<CorrectionResponse>;
+    getCorrection(correctionId: string, signal?: AbortSignal): Promise<CorrectionResponse>;
+    listCorrections(input?: {
+        cursor?: string;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<CorrectionsListResponse>;
     /** Identify the canonical graph subject for one explicitly selected page. */
     identify(input: IdentifySelectedPageInput, signal?: AbortSignal): Promise<IdentifySelectedPageResult>;
     /** Complete producer-owned vectors and classifications for portable colour matching. */

package/catalogue-client.js

@@ -5,6 +5,38 @@ export class CatalogueClient {
     constructor(transport) {
         this.#transport = transport;
     }
+    /** Brand products ranked by observed Material Bank sample-order lines, with window provenance. */
+    brandMostSampled(brandId, options = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("brands.most_sampled"), { query: { brandId, ...options }, signal });
+    }
+    /** Compare canonical Variants without searching or ranking them. */
+    compare(input, signal) {
+        return this.#transport.requestJson(resolveOperation("retrieval.compare"), {
+            body: input,
+            signal,
+        });
+    }
+    /** Submit confirmed caller-authored review work; never changes accepted truth. */
+    createCorrection(input, options) {
+        if (!/^[\x21-\x7e]{1,200}$/.test(options.idempotencyKey))
+            throw new Error("A valid Idempotency-Key is required for Correction submission.");
+        return this.#transport.requestJson(resolveOperation("corrections.create"), {
+            body: input,
+            ...options,
+        });
+    }
+    getCorrection(correctionId, signal) {
+        return this.#transport.requestJson(resolveOperation("corrections.get"), {
+            pathParams: { correctionId },
+            signal,
+        });
+    }
+    listCorrections(input = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("corrections.list"), {
+            query: input,
+            signal,
+        });
+    }
     /** Identify the canonical graph subject for one explicitly selected page. */
     identify(input, signal) {
         return this.#transport.requestJson(resolveOperation("retrieval.identify"), { body: input, signal });

package/compare-types.d.ts

@@ -0,0 +1,89 @@
+export interface CompareInput {
+    variantIds: string[];
+    selection?: {
+        kind: "blocks";
+        blockIds: string[];
+    } | {
+        kind: "attributes";
+        attributeIds: string[];
+    };
+}
+type Availability = "available" | "discontinued" | "superseded" | "unknown";
+type ClaimScope = "variant" | "product" | "brand";
+export interface CompareTarget {
+    variantId: string;
+    version: string;
+    freshness: {
+        oldestAt: string | null;
+        newestAt: string | null;
+    };
+    identity: {
+        variantId: string;
+        variantName: string | null;
+        brand: string;
+        brandSlug: string;
+        product: string;
+        productId: string;
+        colourName: string | null;
+        category: string | null;
+        categoryPath: string[];
+        imageUrl: string | null;
+        installationImageUrl: string | null;
+        dominantHex: string | null;
+        siblingCount: number;
+    };
+    availability: {
+        state: Availability;
+        label: string | null;
+        supersededBy: {
+            variantId: string;
+            brandSlug: string;
+            productId: string;
+            brand: string;
+            product: string;
+            variant: string;
+            color: string | null;
+            availability: Availability;
+        } | null;
+    };
+    sampleability: boolean | null;
+}
+export interface CompareCell {
+    variantId: string;
+    state: "known" | "unknown" | "conflicting" | "inapplicable";
+    recordState: "stated" | "conflicting" | "stale" | "unknown" | "missing" | "not_applicable" | "not_evaluated";
+    value: unknown;
+    unit: string | null;
+    verification: "verified" | "unverified" | "unbacked";
+    confidence: number | null;
+    sourceBasis: string | null;
+    sourceRef: string | null;
+    freshnessAt: string | null;
+    claimScope: ClaimScope | null;
+    competingClaims: {
+        scope: ClaimScope;
+        value: unknown;
+        sourceRef: string | null;
+    }[];
+}
+export interface CompareResult {
+    targets: CompareTarget[];
+    rows: {
+        blockId: string;
+        blockName: string;
+        attributeId: string;
+        label: string;
+        outcome: "same" | "different" | "incomplete" | "indeterminate" | "not_applicable";
+        cells: CompareCell[];
+    }[];
+}
+export interface CompareResponse {
+    data: CompareResult;
+    meta: {
+        operationId: "retrieval.compare";
+        requestId: string;
+    };
+    links: Record<string, never>;
+    warnings: never[];
+}
+export {};

package/compare-types.js

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

package/correction-types.d.ts

@@ -0,0 +1,88 @@
+export type CorrectionJson = null | boolean | number | string | CorrectionJson[] | {
+    [key: string]: CorrectionJson;
+};
+export type CorrectionSubject = {
+    kind: "brand" | "product" | "variant";
+    id: string;
+};
+export type CorrectionTarget = {
+    kind: "identity";
+    subject: CorrectionSubject;
+} | {
+    kind: "attribute";
+    subject: CorrectionSubject;
+    blockId: string;
+    attributeId: string;
+} | {
+    kind: "relationship";
+    subject: CorrectionSubject;
+    relationship: string;
+    relatedSubject: CorrectionSubject;
+} | {
+    kind: "source_interpretation";
+    sourceMaterialId: string;
+    subject?: CorrectionSubject;
+} | {
+    kind: "missing_record";
+    url: string;
+};
+/** Caller-supplied evidence is not an independently verified graph reading. */
+export interface CorrectionEvidence {
+    state: "known" | "unknown" | "conflicting" | "not_applicable";
+    value?: CorrectionJson;
+    sourceUrl?: string;
+    note?: string;
+}
+export interface CreateCorrectionInput {
+    target: CorrectionTarget;
+    pageEvidence: CorrectionEvidence;
+    graphEvidence: CorrectionEvidence;
+    proposedChange: CorrectionJson;
+    rationale: string;
+}
+export interface Correction {
+    id: string;
+    submission: CreateCorrectionInput;
+    status: "submitted" | "in_review" | "resolved" | "withdrawn";
+    resolution: "substantiated" | "not_substantiated" | "duplicate" | "superseded" | "cannot_determine" | null;
+    createdAt: string;
+    updatedAt: string;
+    acceptedTruthChanged: false;
+}
+export interface CorrectionResponse {
+    data: Correction;
+    meta: {
+        operationId: "corrections.create";
+        requestId: string;
+        idempotency: {
+            replayed: boolean;
+        };
+    } | {
+        operationId: "corrections.get";
+        requestId: string;
+    };
+    links: {
+        self: string;
+    };
+    warnings: never[];
+}
+export interface CorrectionsListResponse {
+    data: Correction[];
+    meta: {
+        operationId: "corrections.list";
+        requestId: string;
+        page: {
+            returned: number;
+            total: {
+                value: null;
+                basis: "unavailable";
+            };
+            nextCursor: string | null;
+        };
+    };
+    links: {
+        self: string;
+        next: string | null;
+    };
+    warnings: never[];
+}

package/correction-types.js

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

package/exploration-types.d.ts

@@ -18,6 +18,7 @@ export interface GraphOperatorEvidence {
 export interface CandidateReadInput {
     operator: "looks_like";
     corpusScope?: CorpusScope;
+    /** Return up to 24 ranked candidates (default 8), from one bounded retrieval. */
     limit?: number;
     excludeVariantIds?: VariantId[];
 }

package/http-transport.d.ts

@@ -11,6 +11,8 @@ import { type SdkOperation } from "./operations.js";
 export type QueryValue = string | number | boolean | undefined | null | Array<string | number | boolean>;
 export type QueryParams = Record<string, QueryValue>;
 export interface RequestOptions {
+    /** Required by state-changing operations that support safe retries. */
+    idempotencyKey?: string;
     query?: QueryParams;
     body?: unknown;
     signal?: AbortSignal;

package/http-transport.js

@@ -211,7 +211,12 @@ export class HttpTransport {
         const { parsed } = await this.send({
             method: sdkOperation.method,
             url,
-            headers: this.authHeaders(hasBody ? { "Content-Type": "application/json" } : undefined),
+            headers: this.authHeaders({
+                ...(hasBody ? { "Content-Type": "application/json" } : {}),
+                ...(options.idempotencyKey
+                    ? { "Idempotency-Key": options.idempotencyKey }
+                    : {}),
+            }),
             body: hasBody ? JSON.stringify(options.body) : undefined,
             signal: options.signal,
         });

package/index.d.ts

@@ -1,4 +1,6 @@
 export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
+export type { CompareInput, CompareTarget, CompareCell, CompareResult, CompareResponse, } from "./compare-types.js";
+export type { CorrectionJson, CorrectionSubject, CorrectionTarget, CorrectionEvidence, CreateCorrectionInput, Correction, CorrectionResponse, CorrectionsListResponse, } from "./correction-types.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";
@@ -53,3 +55,4 @@ 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";
 export type { PaletteCompleteInput, PaletteCompleteResponse, PaletteDiscoverInput, PaletteDiscoverResponse, } from "./palette-completion-types.js";
+export type { BrandMostSampledResponse } from "./brand-most-sampled-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 ["colours.complete", "POST", "/api/v1/colours/palettes/complete", "complete_interior_palette"], readonly ["colours.discover", "GET", "/api/v1/colours/palettes", "discover_interior_palettes"], readonly ["samplizeColorVecCache", "GET", "/api/v1/catalogues/samplize/colorvec", "samplize_colorvec_cache"], readonly ["samplizeCatalogueSearch", "POST", "/api/v1/catalogues/samplize/search", "samplize_catalogue_search"], 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 ["identify", "POST", "/api/v1/identify", "retrieval.identify"], 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.list", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments.post", "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"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["brandMostSampled", "GET", "/api/v1/brands/most-sampled", "brands.most_sampled"], readonly ["colours.complete", "POST", "/api/v1/colours/palettes/complete", "complete_interior_palette"], readonly ["colours.discover", "GET", "/api/v1/colours/palettes", "discover_interior_palettes"], readonly ["samplizeColorVecCache", "GET", "/api/v1/catalogues/samplize/colorvec", "samplize_colorvec_cache"], readonly ["samplizeCatalogueSearch", "POST", "/api/v1/catalogues/samplize/search", "samplize_catalogue_search"], 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 ["identify", "POST", "/api/v1/identify", "retrieval.identify"], readonly ["compare", "POST", "/api/v1/compare", "retrieval.compare"], readonly ["createCorrection", "POST", "/api/v1/corrections", "corrections.create"], readonly ["getCorrection", "GET", "/api/v1/corrections/{correctionId}", "corrections.get"], readonly ["listCorrections", "GET", "/api/v1/corrections", "corrections.list"], 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.list", "GET", "/api/v1/source-material/{batchId}/sources/{sourceId}/comments", "list_source_material_comments"], readonly ["sourceMaterialComments.post", "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,12 @@
 import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
+    [
+        "brandMostSampled",
+        "GET",
+        "/api/v1/brands/most-sampled",
+        "brands.most_sampled",
+    ],
     [
         "colours.complete",
         "POST",
@@ -58,6 +64,15 @@ const OPERATION_DEFINITIONS = [
     ],
     ["search", "POST", "/api/v1/search", "search_materials_post"],
     ["identify", "POST", "/api/v1/identify", "retrieval.identify"],
+    ["compare", "POST", "/api/v1/compare", "retrieval.compare"],
+    ["createCorrection", "POST", "/api/v1/corrections", "corrections.create"],
+    [
+        "getCorrection",
+        "GET",
+        "/api/v1/corrections/{correctionId}",
+        "corrections.get",
+    ],
+    ["listCorrections", "GET", "/api/v1/corrections", "corrections.list"],
     ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"],
     [
         "samplizeCatalogue",

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
     },
+    "./webmcp": {
+      "types": "./webmcp.d.ts",
+      "import": "./webmcp.js"
+    },
     "./samplize-colorvec": {
       "types": "./samplize-colorvec.d.ts",
       "import": "./samplize-colorvec.js"

package/samplize-catalogue-types.d.ts

@@ -1,6 +1,11 @@
 export interface SamplizeCatalogueOptions {
     limit?: number;
+    /** Continue with unchanged filters and sourceVersion; omit when filters change. */
     after?: string;
+    /** Exact canonical identities, at most 100. Unknown/ineligible IDs are omitted; no substitution. Combined filters intersect. */
+    variantIds?: string[];
+    /** Exact source collection handle; publisher remains Samplize. */
+    collectionHandle?: string;
     /** Pin every subsequent page to the version returned by the first page. */
     sourceVersion?: string;
 }
@@ -49,6 +54,7 @@ export interface SamplizeCataloguePage {
     corpusScope: "samplizeCatalogue";
     sourceVersion: string;
     source: Record<string, unknown>;
+    /** Number of eligible records matching the supplied filters. */
     total: number;
     items: SamplizeCatalogueProduct[];
     nextCursor: string | null;

package/search-card-types.d.ts

@@ -9,7 +9,7 @@
  * which this module reads `SearchResponse` from.
  */
 import type { ProductId, VariantId } from "./identifiers.js";
-import type { OpenEnum, SearchResponse } from "./types.js";
+import type { OpenEnum, SearchData, SearchResponse } from "./types.js";
 /**
  * The lean `view:"card"` result item — identity + name + thumbnail + score.
  *
@@ -47,7 +47,9 @@ export interface SearchCardItem {
     attributes?: Record<string, string | string[] | null>;
 }
 /** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
-export interface SearchCardResponse extends Omit<SearchResponse, "view" | "results"> {
-    view: OpenEnum<"card">;
-    results: SearchCardItem[];
+export interface SearchCardResponse extends Omit<SearchResponse, "data"> {
+    data: Omit<SearchData, "view" | "results"> & {
+        view: OpenEnum<"card">;
+        results: SearchCardItem[];
+    };
 }

package/search-response-types.d.ts

@@ -0,0 +1,11 @@
+import type { SearchData } from "./types.js";
+/** Canonical Search wire response. Raw SDK methods preserve this envelope. */
+export interface SearchResponse {
+    data: SearchData;
+    meta: {
+        operationId: "search_materials_post" | "search_materials_get";
+        requestId: string;
+    };
+    links: Record<string, never>;
+    warnings: never[];
+}

package/search-response-types.js

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

package/types.d.ts

@@ -1,8 +1,8 @@
+export type { SearchResponse } from "./search-response-types.js";
 import type { ResponseAttribution } from "./attribution-types.js";
 import type { BySpecVerdict } from "./by-spec-types.js";
 /**
  * Hand-mirrored wire types for the MaterialGraph public API (spec 0.5.0).
- *
  * These interfaces intentionally have NO runtime dependency on any
  * `@materialgraph/*` package — they are a standalone, publishable mirror of the
  * shapes in `apps/web/public/openapi.yaml` and the captured fixtures under
@@ -358,7 +358,7 @@ export interface SearchFacets {
  * you asked for it. Follow `cursor` for the rest. "I found 24 materials" is
  * wrong whenever `limit` was 24.
  */
-export interface SearchResponse extends SearchResponseExplainReceipts {
+export interface SearchData extends SearchResponseExplainReceipts {
     /** Result attribution — see {@link ResponseAttribution}. `basis` is `mode` verbatim here. */
     attribution?: ResponseAttribution;
     view: OpenEnum<"full" | "card">;

package/webmcp.d.ts

@@ -0,0 +1,17 @@
+/** Canonical operation contracts. Consumers validate both boundaries and supply their own transport. */
+export interface WebMcpToolContract {
+    readonly name: "identify" | "search" | "compare" | "create_correction";
+    readonly operationId: string;
+    readonly path: string;
+    readonly method: "POST";
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly outputSchema: Readonly<Record<string, unknown>>;
+    readonly annotations: {
+        readonly readOnlyHint: boolean;
+        readonly untrustedContentHint: boolean;
+    };
+    readonly requiresVisibleConfirmation: boolean;
+    readonly requiredHeaders: readonly string[];
+}
+export { WEBMCP_TOOLS } from "./webmcp.generated.js";

package/webmcp.generated.d.ts

@@ -0,0 +1,2 @@
+import type { WebMcpToolContract } from "./webmcp.js";
+export declare const WEBMCP_TOOLS: readonly WebMcpToolContract[];