@instruments/materialgraph 0.45.0 → 1.0.0

package/color-profiles-types.d.ts

@@ -55,6 +55,6 @@ export type ColorProfilesParams = {
     groupBy?: "group" | "type" | "merged";
     /** Representative colors per category, 1 to 64. The server defaults to 8. */
     topN?: number;
-    /** `"diverse"` maximises visual distinctness instead of frequency. */
+    /** `"diverse"` maximizes visual distinctness instead of frequency. */
     select?: "frequency" | "diverse";
 };

package/colors-client.d.ts

@@ -11,9 +11,9 @@ import type { JsonOperationId, OperationResponses } from "./operation-responses.
  * The namespace holds no transport of its own: the client hands it a bound
  * `get`, so auth, rate-limit accounting and error shaping stay in one place.
  *
- * `profiles` is an aggregate and carries a `basis`: it reads a materialized
- * view refreshed on a schedule, not on write, so check how much of the corpus
- * the answer covers before treating it as complete.
+ * `profiles` is an aggregate over a category. It is counted live at request
+ * time from `resolved_variant_bands`, the dominant color of each searchable
+ * variant, so it is as current as the last write to a variant.
  *
  * ROUTING OUT OF THIS NAMESPACE. Color is a lens, and this is not the only
  * door into it:
@@ -35,7 +35,7 @@ export type ColorsTransport = {
 export declare class ColorsClient {
     #private;
     constructor(transport: ColorsTransport);
-    /** Nearest Samplize catalogue paints for up to twelve hexes, deduplicated in input order. */
+    /** Nearest Samplize catalog paints for up to twelve hexes, deduplicated in input order. */
     nearestPaints(params: NearestPaintsParams, signal?: AbortSignal): Promise<NearestPaintsOutput>;
     /**
      * THE QUESTION: "what colors does this CATEGORY come in?" - the
@@ -44,8 +44,8 @@ export declare class ColorsClient {
      *
      * An aggregate over a category, not a list of materials: use
      * `mg.findVariantsByColor()` or `mg.searchVariants()` when you want the
-     * materials themselves. Check `basis` -
-     * this reads a scheduled materialized view, so it can lag the catalogue.
+     * materials themselves. The counts are read live at
+     * request time from `resolved_variant_bands`, so they do not lag the catalog.
      *
      * `groupBy: "group"` takes product-type GROUP keys and merges every leaf type
      * under a group into one histogram BEFORE ranking - a group's palette, not

package/colors-client.js

@@ -3,7 +3,7 @@ export class ColorsClient {
     constructor(transport) {
         this.#transport = transport;
     }
-    /** Nearest Samplize catalogue paints for up to twelve hexes, deduplicated in input order. */
+    /** Nearest Samplize catalog paints for up to twelve hexes, deduplicated in input order. */
     async nearestPaints(params, signal) {
         return await this.#transport.get("find_nearest_paints", { hex: params.hexes, limit: params.limit }, signal);
     }
@@ -14,8 +14,8 @@ export class ColorsClient {
      *
      * An aggregate over a category, not a list of materials: use
      * `mg.findVariantsByColor()` or `mg.searchVariants()` when you want the
-     * materials themselves. Check `basis` -
-     * this reads a scheduled materialized view, so it can lag the catalogue.
+     * materials themselves. The counts are read live at
+     * request time from `resolved_variant_bands`, so they do not lag the catalog.
      *
      * `groupBy: "group"` takes product-type GROUP keys and merges every leaf type
      * under a group into one histogram BEFORE ranking - a group's palette, not

package/errors.d.ts

@@ -26,6 +26,8 @@ export type ProblemDetail = {
 };
 /** Normalized residual `{ error }` body. Unknown response fields are discarded. */
 export type SimpleErrorBody = {
+    /** The vector and variant routes' machine-readable code, when the body is `{ code, message }`. */
+    code?: string;
     error: string;
     issues?: SanitizedIssue[];
 };

package/errors.js

@@ -157,10 +157,23 @@ const normalizeProblem = (body, secrets) => {
     };
 };
 const normalizeSimple = (body, secrets) => {
-    if (!isRecord(body) || typeof body.error !== "string") {
+    if (!isRecord(body)) {
         return undefined;
     }
     const issues = sanitizeIssues(body.issues, secrets);
+    // `{ code, message }` is the vector routes' error body; keep its code.
+    if (typeof body.error !== "string" &&
+        typeof body.code === "string" &&
+        typeof body.message === "string") {
+        return {
+            code: safeString(body.code, secrets),
+            error: safeString(body.message, secrets),
+            ...(issues === undefined ? {} : { issues }),
+        };
+    }
+    if (typeof body.error !== "string") {
+        return undefined;
+    }
     return {
         error: safeString(body.error, secrets),
         ...(issues === undefined ? {} : { issues }),
@@ -211,7 +224,12 @@ export class MaterialGraphError extends Error {
         });
     }
     static fromTransport(input) {
-        if (input.callerSignal?.aborted === true) {
+        // A deadline (`AbortSignal.timeout`, or the client's `timeoutMs`) aborts
+        // the signal with a TimeoutError reason: that is a timeout, not a
+        // cancellation by the caller.
+        const reason = input.callerSignal?.reason;
+        const reasonName = reason instanceof Error ? reason.name : "";
+        if (input.callerSignal?.aborted === true && reasonName !== "TimeoutError") {
             return new MaterialGraphError("MaterialGraph request aborted by caller", {
                 ...requestMetadata(input),
                 kind: "aborted",
@@ -219,7 +237,7 @@ export class MaterialGraphError extends Error {
             });
         }
         const name = input.cause instanceof Error ? input.cause.name : "";
-        if (name === "TimeoutError") {
+        if (name === "TimeoutError" || reasonName === "TimeoutError") {
             return new MaterialGraphError("MaterialGraph request timed out", {
                 ...requestMetadata(input),
                 kind: "timeout",

package/find-sampled-together-types.d.ts

@@ -65,8 +65,8 @@ export type FindSampledTogetherOutput = {
         variantId: string;
         variantName: string | null;
     }[];
-    /** Seed ids outside the materials catalogue; present only when at least one was. */
-    excludedBySearchCatalogueSubset?: string[];
+    /** Seed ids outside the materials catalog; present only when at least one was. */
+    excludedBySearchCatalogSubset?: string[];
     /** References that matched no variant. */
     unresolved: string[];
 };

package/find-variants-by-color-types.d.ts

@@ -12,7 +12,7 @@ import type { ImageReferenceInput } from "./image-reference-types.js";
  * are copied here rather than imported. `contract-parity.test.ts` keeps this
  * mirror honest against the server types.
  */
-import type { SearchCatalogueSubset, SearchCatalogueSubsetReceipt } from "./search-catalogue-subset-types.js";
+import type { SearchCatalogSubset, SearchCatalogSubsetReceipt } from "./search-catalog-subset-types.js";
 export type FindVariantsByColorMode = "contains" | "palette" | "rerank";
 /** One color condition. `role` defaults to `required`; every other field defaults to absent/false/0. */
 export type ColorConditionInput = {
@@ -33,7 +33,7 @@ export type FindVariantsByColorInput = {
     colors?: ColorConditionInput[];
     /** Material Bank category IDs or exact source paths, including descendants against actual memberships. Materials and decking only. */
     categoryIds?: string[];
-    searchCatalogueSubset?: SearchCatalogueSubset;
+    searchCatalogSubset?: SearchCatalogSubset;
     cursor?: string;
     /** Palette only: targets from this image's colors, not `colors[]`. */
     image?: ImageReferenceInput;
@@ -67,7 +67,7 @@ export type PaintCatalogVariant = {
     variantName: string | null;
 };
 export type ResolvedColor = {
-    catalogueVariant: PaintCatalogVariant | null;
+    catalogVariant: PaintCatalogVariant | null;
     hex: string;
     index: number;
     /** `region`: a named meaning's own OKLCh bounds, kept — never collapsed to one hex. */
@@ -194,9 +194,9 @@ export type CompareColorSimilarityReference = {
 };
 export type FindVariantsByColorRerankResult = {
     /** Present ONLY when the request narrowed it. ABSENT means the whole graph. */
-    searchCatalogueSubset?: SearchCatalogueSubsetReceipt;
-    /** Real variant ids outside `searchCatalogueSubset` or the materials catalogue. Present when a scope narrowed or any was excluded. */
-    excludedBySearchCatalogueSubset?: string[];
+    searchCatalogSubset?: SearchCatalogSubsetReceipt;
+    /** Real variant ids outside `searchCatalogSubset` or the materials catalog. Present when a scope narrowed or any was excluded. */
+    excludedBySearchCatalogSubset?: string[];
     /** Candidates ranked by ascending color distance; unembedded ones last. */
     matches: ColorRankMatch[];
     mode: "rerank";

package/find-variants-by-vector-types.d.ts

@@ -8,13 +8,13 @@ import type { PaintCatalogVariant } from "./find-variants-by-color-types.js";
  * are copied here and `contract-parity.test.ts` keeps them honest.
  */
 import type { ImageReferenceInput } from "./image-reference-types.js";
-import type { FilterGroups, ListVariantsItem } from "./list-variants-types.js";
-import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
+import type { FilterGroups, VariantCard } from "./list-variants-types.js";
+import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
 export declare const FIND_VARIANTS_BY_VECTOR_MODES: readonly ["text", "image", "text_and_image"];
 export type FindVariantsByVectorMode = (typeof FIND_VARIANTS_BY_VECTOR_MODES)[number];
 export type FindVariantsByVectorQuery = {
-    /** Exactly one reference. Only for image modes. */
-    image?: ImageReferenceInput;
+    /** One to six image references, each with exactly one field. Several are combined into one query, and every seed image's variant is left out. Only for image modes. Each image that has to be embedded spends one of the embed requests. */
+    images?: ImageReferenceInput[];
     mode: FindVariantsByVectorMode;
     /** Description, mood words included. Only for text modes. */
     text?: string;
@@ -29,9 +29,9 @@ export type FindVariantsByVectorInput = {
     limit?: number;
     query: FindVariantsByVectorQuery;
     /** Only this corpus scope. Absent or all: every variant. */
-    searchCatalogueSubset?: SearchCatalogueSubset;
+    searchCatalogSubset?: SearchCatalogSubset;
 };
-export type FindVariantsByVectorItem = Omit<ListVariantsItem, "materialBankId"> & {
+export type FindVariantsByVectorItem = Omit<VariantCard, "materialBankId"> & {
     /** The variant's Material Bank SKU; null means none is recorded. Always present here, unlike `list_variants`' optional field. */
     materialBankId: string | null;
     /** Voyage cosine to the query. Ranks only; not a probability. */
@@ -40,7 +40,7 @@ export type FindVariantsByVectorItem = Omit<ListVariantsItem, "materialBankId">
 export type FindVariantsByVectorReference = {
     id: string;
     kind: "url" | "assetId" | "variantId" | "sourceId";
-} | null;
+};
 export type FindVariantsByVectorScan = {
     /** True when no further candidates match; false means more may exist. */
     exhausted: boolean;
@@ -57,12 +57,13 @@ export type FindVariantsByVectorTimings = {
     verifyMs: number;
 };
 export type FindVariantsByVectorOutput = {
-    /** Explicit `{field: "variant", op: "in"}` filter ids that name a real variant outside the materials catalogue — present only when at least one did. */
-    excludedBySearchCatalogueSubset?: string[];
+    /** Explicit `{field: "variant", op: "in"}` filter ids that name a real variant outside the materials catalog — present only when at least one did. */
+    excludedBySearchCatalogSubset?: string[];
     items: FindVariantsByVectorItem[];
     mode: FindVariantsByVectorMode;
-    reference: FindVariantsByVectorReference;
-    /** The exact brand paint named by the text query, when held in the catalogue. */
+    /** The image references the query used, in order. Empty in text mode. */
+    references: FindVariantsByVectorReference[];
+    /** The exact brand paint named by the text query, when held in the catalog. */
     namedPaint?: PaintCatalogVariant;
     scan: FindVariantsByVectorScan;
     timings: FindVariantsByVectorTimings;

package/get-variant-types.d.ts

@@ -15,6 +15,30 @@ export type GetVariantOptions = {
     attributes?: readonly string[];
     /** Canonical block ids, returned whole, e.g. `["acoustic"]`. */
     blocks?: readonly string[];
+    /** Add `ifc`: the IFC 4.3 manufacturer property set and classification references. */
+    ifc?: boolean;
+};
+/**
+ * The variant as an IFC 4.3 type states it. Properties the record does not
+ * hold are left out, so an absent property is unknown.
+ */
+export type GetVariantIfc = {
+    propertySets: {
+        name: "Pset_ManufacturerTypeInformation";
+        properties: {
+            name: string;
+            value: string;
+            dataType: "IfcLabel" | "IfcIdentifier";
+            /** The property's bSDD URI. */
+            uri: string;
+        }[];
+    }[];
+    classificationReferences: {
+        classification: "MasterFormat" | "OmniClass" | "UniFormat";
+        identification: string;
+        name?: string;
+        edition?: string;
+    }[];
 };
 /**
  * One variant: the compact identity, and `specifications` only for the
@@ -71,6 +95,8 @@ export type GetVariantOutput = {
     name: string;
     /** Requested blocks or attributes the variant's product type does not carry. */
     notApplicable?: ListVariantsNotApplicable;
+    /** Present when `ifc` was asked for. */
+    ifc?: GetVariantIfc;
     product: {
         id: string;
         name: string;

package/http-transport.d.ts

@@ -35,6 +35,8 @@ export type HttpTransportOptions = {
     apiKey: string;
     baseUrl: string;
     fetch: typeof fetch;
+    /** Deadline in milliseconds for each JSON or upload request. Not applied to streams. */
+    timeoutMs?: number;
 };
 export declare class HttpTransport {
     #private;

package/http-transport.js

@@ -32,11 +32,23 @@ export class HttpTransport {
     baseUrl;
     apiKey;
     fetch;
+    #timeoutMs;
     #lastRateLimit = null;
     constructor(options) {
         this.apiKey = options.apiKey;
         this.baseUrl = options.baseUrl.replace(/\/+$/u, "");
         this.fetch = options.fetch;
+        this.#timeoutMs = options.timeoutMs;
+    }
+    /** The caller's signal and the client deadline, whichever fires first. */
+    #withDeadline(signal) {
+        if (this.#timeoutMs === undefined) {
+            return signal;
+        }
+        const deadline = AbortSignal.timeout(this.#timeoutMs);
+        return signal === undefined
+            ? deadline
+            : AbortSignal.any([signal, deadline]);
     }
     get lastRateLimit() {
         return this.#lastRateLimit;
@@ -83,19 +95,21 @@ export class HttpTransport {
             origin: requestUrl.origin,
             path: requestUrl.pathname,
         };
+        // The deadline covers the whole request, body read included.
+        const signal = this.#withDeadline(input.signal);
         let response;
         try {
             response = await this.fetch(input.url, {
                 body: input.body,
                 headers: input.headers,
                 method: input.method,
-                signal: input.signal,
+                signal,
             });
         }
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                callerSignal: input.signal,
+                callerSignal: signal,
                 cause,
             });
         }
@@ -108,7 +122,7 @@ export class HttpTransport {
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                callerSignal: input.signal,
+                callerSignal: signal,
                 cause,
             });
         }

package/identifiers.d.ts

@@ -63,7 +63,7 @@ export type SlotId = OpaqueId;
 /**
  * A pagination cursor. Opaque keyset state, not an offset and not a page
  * number: pass the value you were handed back unchanged to continue, and never
- * synthesise one. A response with no cursor is the end of the walk.
+ * synthesize one. A response with no cursor is the end of the walk.
  *
  * A cursor is only valid for the query that produced it — changing sort,
  * filters or limit invalidates it.

package/image-reference-types.d.ts

@@ -2,12 +2,12 @@
  * @module image-reference-types
  * @description The one image-reference shape the vector-discovery lenses
  * share (`@materialgraph/search/vector-discovery/image-reference`'s
- * `imageReferenceInputSchema`): a catalogue asset, an upload, a public URL,
+ * `imageReferenceInputSchema`): a catalog asset, an upload, a public URL,
  * or an existing variant's own image. Exactly one field is set per call; the
  * server refuses more than one.
  */
 export type ImageReferenceInput = {
-    /** Catalogue asset id. */
+    /** Catalog asset id. */
     assetId?: string;
     /** Upload id (`smf_...`) from source-material. */
     sourceId?: string;

package/index.d.ts

@@ -1,10 +1,10 @@
 export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
 export type { MaterialGraphClientOptions } from "./client.js";
-export type { FilterOp, FilterTermCondition, FilterNumericCondition, FilterPresenceCondition, FilterAnyFieldCondition, FilterCondition, FilterGroups, OptionalFilterGroups, OrderByEntry, ListVariantsInclude, ListVariantsCollapse, ColorRegion, ColorRangeCondition, ListVariantsInput, ListVariantsPreference, ListVariantsSpecifications, ListVariantsNotApplicable, SampleSubject, ListVariantsItem, ListVariantsOutput, } from "./list-variants-types.js";
+export type { FilterOp, FilterTermCondition, FilterNumericCondition, FilterPresenceCondition, FilterAnyFieldCondition, FilterCondition, FilterGroups, OptionalFilterGroups, OrderByEntry, ListVariantsInclude, ListVariantsCollapse, ColorRegion, ColorRangeCondition, ListVariantsInput, ListVariantsPreference, ListVariantsSpecifications, ListVariantsNotApplicable, SampleSubject, ListVariantsItem, ListVariantsOutput, VariantCard, } from "./list-variants-types.js";
 export type { ListVariantFacetsInput, VariantFacetValue, CategoricalVariantFacet, BooleanVariantFacet, NumericVariantFacet, VariantFacet, ListVariantFacetsOutput, } from "./list-variant-facets-types.js";
 export type { SearchVariantsSelection, SearchVariantsInput, SearchVariantsUnderstood, SearchVariantsReading, SearchVariantsChoice, SearchVariantsOutput, } from "./search-variants-types.js";
 export type { ListEnumValuesOptions, EnumValueMatch, EnumValueItem, ListEnumValuesResult, } from "./list-enum-values-types.js";
-export type { GetVariantOptions, GetVariantOutput, } from "./get-variant-types.js";
+export type { GetVariantIfc, GetVariantOptions, GetVariantOutput, } from "./get-variant-types.js";
 export type { ImageReferenceInput } from "./image-reference-types.js";
 export type { SampledTogetherProjectType, FindSampledTogetherInput, FindSampledTogetherRow, FindSampledTogetherOutput, } from "./find-sampled-together-types.js";
 export type { FindVariantsByColorMode, ColorConditionInput, FindVariantsByColorInput, ColorConditionReceipt, PaintCatalogVariant, ResolvedColor, ColorAlternative, UnresolvedColor, ColorVariantMatch, ColorPageInfo, FindVariantsByColorContainsResult, FindVariantsByColorPaletteResult, ColorRankedSeed, ColorRankMatch, ResolvedColorReference, CompareColorSimilarityReference, FindVariantsByColorRerankResult, FindVariantsByColorOutput, } from "./find-variants-by-color-types.js";
@@ -17,9 +17,9 @@ export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type { FileInput, UploadSourceMaterialInput, SourceMaterialReceiptFile, SourceMaterialBatchReceipt, PublicRunStatus, PublicRunFailure, PublicRunArtifactRef, PublicRun, CreatePublicRunRequest, CreatePublicRunResponse, PublicRunResponse, RunEvent, StreamRunEventsOptions, DrainRunEventsOptions, } from "./run-types.js";
 export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
-export type { OpenEnum, JsonValue, OklabTriple, MaterialColor, ImageSource, MaterialAvailability, MaterialTile, DemandMomentum, CompanionDemand, ProjectTypeShare, CospecPairing, ColorPairing, PairingOrderMode, PairingRanking, PairingOrdering, PairingItem, PairingsResponse, AttributeMatch, AttributeListItem, OutsideScopeAttribute, ListAttributesResult, WhoamiResponse, PairingsOptions, ListAttributesOptions, ExtractedPalette, ExtractPaletteResponse, ExtractPaletteInput, ResolveValueCandidate, ValueResolution, ResolveColorOptions, ResolveColorCatalogueVariant, ResolveColorVariant, ResolveColorResponse, BySpecVerdictState, BySpecVerdictCell, BySpecVerdict, MaterialVerdict, BySpecUnresolvedCriterion, } from "./types.js";
+export type { OpenEnum, JsonValue, OklabTriple, MaterialColor, ImageSource, MaterialAvailability, MaterialTile, DemandMomentum, CompanionDemand, ProjectTypeShare, CospecPairing, ColorPairing, PairingOrderMode, PairingRanking, PairingOrdering, PairingItem, PairingsResponse, AttributeMatch, AttributeListItem, OutsideScopeAttribute, ListAttributesResult, WhoamiResponse, PairingsOptions, ListAttributesOptions, ExtractedPalette, ExtractPaletteResponse, ExtractPaletteInput, ResolveValueCandidate, ValueResolution, ResolveColorOptions, ResolveColorCatalogVariant, ResolveColorVariant, ResolveColorResponse, BySpecVerdictState, BySpecVerdictCell, BySpecVerdict, MaterialVerdict, BySpecUnresolvedCriterion, } from "./types.js";
 export type { ResolveVariantInput, ResolveVariantSubject, ResolveVariantEvidence, ResolveVariantReceipt, ResolveVariantUnresolvedReason, ResolveVariantOutput, } from "./resolve-variant-types.js";
-export type { CatalogueReference, CatalogueReferenceAbsenceReason, CatalogueReferencePublication, CatalogueReferenceResult, CatalogueReferenceBatchResponse, CatalogueCollectionsOptions, CatalogueCollectionSampleProduct, CatalogueChannelCollection, CatalogueChannelCollectionsResponse, CatalogueDocumentAccess, CatalogueDocumentAccessResult, CatalogDocument, CatalogEdition, CatalogAvailableReceipt, CatalogFailureReceipt, UnavailableCatalogDocument, CatalogPublication, CatalogDocumentList, CatalogProductReferenceList, CatalogProductReferenceUnavailable, CatalogProductReferenceReadResult, CataloguePageRequiredArtifact, CataloguePageAvailableArtifact, CataloguePage, CatalogPageListResult, CataloguePageRepresentationReadResult, } from "./catalogue-types.js";
+export type { CatalogReference, CatalogReferenceAbsenceReason, CatalogReferencePublication, CatalogReferenceResult, CatalogReferenceBatchResponse, CatalogCollectionsOptions, CatalogCollectionSampleProduct, CatalogChannelCollection, CatalogChannelCollectionsResponse, CatalogDocumentAccess, CatalogDocumentAccessResult, CatalogDocument, CatalogEdition, CatalogAvailableReceipt, CatalogFailureReceipt, UnavailableCatalogDocument, CatalogPublication, CatalogDocumentList, CatalogProductReferenceList, CatalogProductReferenceUnavailable, CatalogProductReferenceReadResult, CatalogPageRequiredArtifact, CatalogPageAvailableArtifact, CatalogPage, CatalogPageListResult, CatalogPageRepresentationReadResult, } from "./catalog-types.js";
 export { CategoriesClient } from "./categories-client.js";
 export type { CategoryRef, CategoryKind, CategoryMatch, CategoryItem, CategoriesPageInfo, CategoriesListInput, CategoriesListResult, CategoryConcept, CategoryProductCategory, CategoriesGetResult, } from "./category-types.js";
 export { ColorsClient } from "./colors-client.js";
@@ -30,5 +30,5 @@ export type { BrandsOptions, BrandItem, ListBrandsPage, } from "./brand-types.js
 export type { VariantAssetAvailability, VariantImageRole, VariantImagePresentation, VariantDocumentType, VariantAssetKind, VariantAssetItem, VariantDocumentCoverageState, VariantAssetPageInfo, ListVariantAssetsOptions, VariantAssetPage, MaterialDocumentStatus, MaterialDocumentCoverageState, MaterialDocumentScope, MaterialDocumentSource, MaterialDocumentProjectionItem, MaterialDocumentCoverageSource, MaterialDocumentCoverage, MaterialDocumentCoverageSummary, MaterialDocumentPageOptions, MaterialDocumentPage, } from "./material-asset-types.js";
 export type { MaterialCoverageStatus, MaterialBlockStatus, MaterialBlockFieldStatus, MaterialBlockFieldValue, MaterialBlockProjectionField, MaterialBlockProjectionItem, MaterialBlockProjection, VariantColorPalette, } from "./material-block-types.js";
 export type { SchemaResource, SCHEMA_RESOURCE_OPERATION_IDS, SchemaResourceRequest, SchemaLifecycle, SchemaExternalMapping, SchemaMatchStrength, SchemaValueDictionaryTerm, SchemaValueDictionaryItem, SchemaResourceItemMap, SchemaResourceResponse, } from "./schema-resource-types.js";
-export type { SamplizePublicationSource, SamplizeLrvObservation, SamplizeDemand, SamplizeCollectionMembership, SamplizeCatalogueOptions, SamplizeCataloguePage, SamplizeCatalogueProduct, SamplizeHexObservation, } from "./samplize-catalogue-types.js";
+export type { SamplizePublicationSource, SamplizeLrvObservation, SamplizeDemand, SamplizeCollectionMembership, SamplizeCatalogOptions, SamplizeCatalogPage, SamplizeCatalogProduct, SamplizeHexObservation, } from "./samplize-catalog-types.js";
 export type { NearestPaintsParams, NearestPaintCard, NearestPaintsHexResult, NearestPaintsOutput, } from "./nearest-paints-types.js";

package/list-variant-facets-types.d.ts

@@ -8,13 +8,13 @@ import type { FilterGroups } from "./list-variants-types.js";
  * dependency on `@materialgraph/search`, so the shapes are copied here and
  * `contract-parity.test.ts` keeps them honest.
  */
-import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
+import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
 export type ListVariantFacetsInput = {
     /** 1–10 facetable attribute ids, or `brand`. Find attribute ids with `listAttributes()`. */
     attributeIds: string[];
     /** The same kind-grouped filter tree `listVariants()` takes. */
     /** Count only this corpus scope; absent or `all` counts every variant. */
-    searchCatalogueSubset?: SearchCatalogueSubset;
+    searchCatalogSubset?: SearchCatalogSubset;
     filters?: FilterGroups;
     /** Top values per categorical or boolean facet, 1–50. Defaults to 10. */
     valuesPerFacet?: number;

package/list-variants-types.d.ts

@@ -9,7 +9,7 @@
  * copied here rather than imported. `contract-parity.test.ts` keeps this
  * mirror honest against the server types.
  */
-import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
+import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
 export type FilterOp = "in" | "not_in" | "all" | "exists" | "missing" | "eq" | "gt" | "gte" | "lt" | "lte";
 export type FilterTermCondition = {
     field: string;
@@ -132,7 +132,7 @@ export type ListVariantsInput = {
      * Only variants in this corpus scope: the rows, the page and the cursor.
      * Absent or `all` is every variant.
      */
-    searchCatalogueSubset?: SearchCatalogueSubset;
+    searchCatalogSubset?: SearchCatalogSubset;
     cursor?: string;
     /** Every condition, across `terms`/`numbers`/`presence`/`anyField`, must match. */
     filters?: FilterGroups;
@@ -222,9 +222,18 @@ export type ListVariantsItem = {
     variantCount?: number;
     variantId: string;
 };
+/**
+ * The variant card both `listVariants` rows and `findVariantsByVector` rows
+ * satisfy. The only difference between the two is the Material Bank SKU:
+ * absent in a list row when none is recorded, `null` in a vector row.
+ */
+export type VariantCard = Omit<ListVariantsItem, "materialBankId"> & {
+    /** The variant's Material Bank SKU. Absent or null means none is recorded. */
+    materialBankId?: string | null;
+};
 export type ListVariantsOutput = {
-    /** Explicit `{field: "variant", op: "in"}` ids that name a real variant outside the materials catalogue. Present only when at least one did. */
-    excludedBySearchCatalogueSubset?: string[];
+    /** Explicit `{field: "variant", op: "in"}` ids that name a real variant outside the materials catalog. Present only when at least one did. */
+    excludedBySearchCatalogSubset?: string[];
     items: ListVariantsItem[];
     /** Present only when a `name` lookup's first page was empty: each name word, and whether a name in scope starts it. The lookup left out the unmatched words and looked again, unless every word or none matched. */
     nameWords?: {
@@ -237,7 +246,7 @@ export type ListVariantsOutput = {
     };
     /** False: nothing from this page on meets any `optionalFilters` entry. Absent when not measured. */
     preferenceMatchesRemain?: boolean;
-    /** Explicit `{field: "variant", op: "in"}` ids that name a variant in the materials catalogue that this list cannot show in the requested `searchCatalogueSubset`: retired, not orderable, or outside the scope. Read one with `getVariant`. Present only when at least one did. */
+    /** Explicit `{field: "variant", op: "in"}` ids that name a variant in the materials catalog that this list cannot show in the requested `searchCatalogSubset`: retired, not orderable, or outside the scope. Read one with `getVariant`. Present only when at least one did. */
     unavailableVariantIds?: string[];
     /** Explicit `{field: "variant", op: "in"}` ids anywhere in `filters.terms` that name no variant at all. */
     unresolvedVariantIds?: string[];

package/material-asset-types.d.ts

@@ -21,7 +21,7 @@ export type VariantImageRole = OpenEnum<"product" | "swatch" | "detail" | "scene
 /** How an image must be framed, a different question from what it shows. */
 export type VariantImagePresentation = OpenEnum<"edge_to_edge" | "packshot" | "cutout_margin" | "montage" | "unknown">;
 /** What a document is for; a document can carry more than one purpose. */
-export type VariantDocumentType = OpenEnum<"technical_data_sheet" | "product_sheet" | "technical_bulletin" | "sustainability_report" | "specification" | "installation_guide" | "care_maintenance_guide" | "operation_manual" | "warranty" | "parts_list" | "technical_drawing" | "test_report" | "certificate" | "declaration_of_performance" | "environmental_product_declaration" | "health_product_declaration" | "ingredient_disclosure" | "safety_data_sheet" | "brochure" | "catalogue" | "color_finish_chart" | "other" | "unknown">;
+export type VariantDocumentType = OpenEnum<"technical_data_sheet" | "product_sheet" | "technical_bulletin" | "sustainability_report" | "specification" | "installation_guide" | "care_maintenance_guide" | "operation_manual" | "warranty" | "parts_list" | "technical_drawing" | "test_report" | "certificate" | "declaration_of_performance" | "environmental_product_declaration" | "health_product_declaration" | "ingredient_disclosure" | "safety_data_sheet" | "brochure" | "catalog" | "color_finish_chart" | "other" | "unknown">;
 /** Every asset kind the registry knows. */
 export type VariantAssetKind = OpenEnum<"image" | "document" | "cad" | "bim" | "model_3d" | "texture" | "archive" | "other" | "unknown">;
 /**

package/operation-responses.d.ts

@@ -1,7 +1,7 @@
 /** Response types belong to operation ids, never a caller-selected generic. */
 import type { ApplicabilityResponse, DeclaredAssociationsResponse } from "./association-types.js";
 import type { ListBrandsPage } from "./brand-types.js";
-import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
+import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogChannelCollectionsResponse, CatalogDocumentAccessResult, CatalogPageRepresentationReadResult, CatalogReferenceBatchResponse } from "./catalog-types.js";
 import type { CategoriesGetResult, CategoriesListResult } from "./category-types.js";
 import type { CategoryColorProfilesResponse } from "./color-profiles-types.js";
 import type { FindSampledTogetherOutput } from "./find-sampled-together-types.js";
@@ -16,13 +16,13 @@ import type { MaterialBlockProjection } from "./material-block-types.js";
 import type { NearestPaintsOutput } from "./nearest-paints-types.js";
 import type { ResolveVariantOutput } from "./resolve-variant-types.js";
 import type { CreatePublicRunResponse, PublicRunResponse, SourceMaterialBatchReceipt } from "./run-types.js";
-import type { SamplizeCataloguePage } from "./samplize-catalogue-types.js";
+import type { SamplizeCatalogPage } from "./samplize-catalog-types.js";
 import type { SchemaResourceResponse } from "./schema-resource-types.js";
 import type { SearchVariantsOutput } from "./search-variants-types.js";
 import type { ExtractPaletteResponse, ListAttributesResult, PairingsResponse, ResolveColorResponse, WhoamiResponse } from "./types.js";
 export type OperationResponses = {
     find_nearest_paints: NearestPaintsOutput;
-    get_catalogue_generation: {
+    get_catalog_generation: {
         generation: number;
     };
     catalog_list_attributes: ListAttributesResult;
@@ -33,9 +33,9 @@ export type OperationResponses = {
     find_variants_by_color: FindVariantsByColorOutput;
     find_variants_by_vector: FindVariantsByVectorOutput;
     get_applicability: ApplicabilityResponse;
-    get_catalog_page_representation: CataloguePageRepresentationReadResult;
-    get_catalogue_document_access: CatalogueDocumentAccessResult;
-    get_catalogue_references_batch: CatalogueReferenceBatchResponse;
+    get_catalog_page_representation: CatalogPageRepresentationReadResult;
+    get_catalog_document_access: CatalogDocumentAccessResult;
+    get_catalog_references_batch: CatalogReferenceBatchResponse;
     get_category: CategoriesGetResult;
     get_category_color_profiles: CategoryColorProfilesResponse;
     get_material_pairings: PairingsResponse;
@@ -47,7 +47,7 @@ export type OperationResponses = {
     list_catalog_documents: CatalogDocumentList;
     list_catalog_pages: CatalogPageListResult;
     list_catalog_product_references: CatalogProductReferenceReadResult;
-    list_catalogue_channel_collections: CatalogueChannelCollectionsResponse;
+    list_catalog_channel_collections: CatalogChannelCollectionsResponse;
     list_categories: CategoriesListResult;
     list_material_blocks: MaterialBlockProjection;
     list_material_documents: MaterialDocumentPage;
@@ -57,7 +57,7 @@ export type OperationResponses = {
     list_variants: ListVariantsOutput;
     resolve_color_name: ResolveColorResponse;
     resolve_variant: ResolveVariantOutput;
-    samplize_catalogue_products: SamplizeCataloguePage;
+    samplize_catalog_products: SamplizeCatalogPage;
     search_variants: SearchVariantsOutput;
     upload_source_material: SourceMaterialBatchReceipt;
     whoami: WhoamiResponse;

package/operations.generated.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.8.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["colors.nearestPaints", "GET", "/api/v1/colors/nearest-paints", "find_nearest_paints"], readonly ["getCatalogueGeneration", "GET", "/api/v1/catalog/generation", "get_catalogue_generation"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], readonly ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_document_access"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColor", "GET", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findSampledTogether", "GET", "/api/v1/variants/sampled-together", "find_sampled_together"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColor", "GET", "/api/v1/search/colors/resolve", "resolve_color_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colors.profiles", "GET", "/api/v1/colors/profiles", "get_category_color_profiles"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["workflows.start", "POST", "/api/v1/workflows/{workflowId}/runs", "create_public_run"], readonly ["workflows.run", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}", "get_public_run"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["colors.nearestPaints", "GET", "/api/v1/colors/nearest-paints", "find_nearest_paints"], readonly ["getCatalogGeneration", "GET", "/api/v1/catalog/generation", "get_catalog_generation"], 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 ["samplizeCatalog", "GET", "/api/v1/catalogs/samplize/products", "samplize_catalog_products"], readonly ["catalogReferencesForVariants", "POST", "/api/v1/catalogs/references", "get_catalog_references_batch"], readonly ["catalogCollections", "GET", "/api/v1/catalogs/collections", "list_catalog_channel_collections"], readonly ["catalogDocumentAccess", "GET", "/api/v1/catalogs/documents/{documentId}", "get_catalog_document_access"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColor", "GET", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findSampledTogether", "GET", "/api/v1/variants/sampled-together", "find_sampled_together"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColor", "GET", "/api/v1/search/colors/resolve", "resolve_color_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colors.profiles", "GET", "/api/v1/colors/profiles", "get_category_color_profiles"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["workflows.start", "POST", "/api/v1/workflows/{workflowId}/runs", "create_public_run"], readonly ["workflows.run", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}", "get_public_run"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation<K extends SdkOperationId = SdkOperationId> = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];