@instruments/materialgraph 3.0.1 → 3.1.0

package/client.d.ts

@@ -177,7 +177,7 @@ export declare class MaterialGraphClient {
      * materials catalog, never silently dropped from the page.
      *
      * `filters`/`optionalFilters`/`orderBy`/`colors` are sent as URL-encoded
-     * JSON; `attributes`/`include`/`words` as comma-separated lists — the server
+     * JSON; `attributes`/`observations`/`include`/`words` as comma-separated lists — the server
      * validates, this method does not duplicate that check.
      */
     listVariants(input: ListVariantsInput, signal?: AbortSignal): Promise<ListVariantsOutput>;

package/client.js

@@ -181,6 +181,9 @@ export class MaterialGraphClient {
             blocks: options?.blocks !== undefined && options.blocks.length > 0
                 ? options.blocks.join(",")
                 : undefined,
+            observations: options?.observations !== undefined && options.observations.length > 0
+                ? options.observations.join(",")
+                : undefined,
             ifc: options?.ifc === true ? "true" : undefined,
         }, signal, { variantId });
     }
@@ -249,7 +252,7 @@ export class MaterialGraphClient {
      * materials catalog, never silently dropped from the page.
      *
      * `filters`/`optionalFilters`/`orderBy`/`colors` are sent as URL-encoded
-     * JSON; `attributes`/`include`/`words` as comma-separated lists — the server
+     * JSON; `attributes`/`observations`/`include`/`words` as comma-separated lists — the server
      * validates, this method does not duplicate that check.
      */
     async listVariants(input, signal) {
@@ -269,6 +272,9 @@ export class MaterialGraphClient {
                 : undefined,
             limit: input.limit,
             name: input.name,
+            observations: input.observations !== undefined && input.observations.length > 0
+                ? input.observations.join(",")
+                : undefined,
             optionalFilters: input.optionalFilters
                 ? JSON.stringify(input.optionalFilters)
                 : undefined,

package/color-wire-types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The ColorScope shapes `resolveColor` returns, as they arrive on the wire.
+ * They mirror `@materialinstruments/colorscope` (14.x) rather than importing
+ * it: the published SDK carries no dependency, and ColorScope is private.
+ */
+import type { OpenEnum } from "./types.js";
+/** A color in OKLab: lightness 0 to 1, and the green-red and blue-yellow axes. */
+export type OKLab = {
+    L: number;
+    a: number;
+    b: number;
+};
+/** A region of color: chroma, hue (null for neutrals) and lightness bounds. */
+export type ColorRegion = {
+    chroma: [number, number];
+    hue: [number, number] | null;
+    lightness: [number, number];
+};
+/** One of ColorScope's fifteen color families. */
+export type ColorFamilyId = OpenEnum<"beige" | "black" | "blue" | "brown" | "cream" | "gray" | "green" | "orange" | "pink" | "purple" | "red" | "taupe" | "teal" | "white" | "yellow">;
+/** A named color a resolution lands on, and how close the input is to it. */
+export type ColorResolutionMatch = {
+    band: OpenEnum<"inside" | "near" | "far">;
+    family: ColorFamilyId;
+    hex: string;
+    id: string;
+    name: string;
+    range: ColorRegion;
+};
+/** What ColorScope makes of a color name: resolved to a color, or why not. */
+export type ColorResolution = {
+    kind: "resolved";
+    confidence: number;
+    input: string;
+    principal: ColorResolutionMatch;
+    others: ColorResolutionMatch[];
+    reference?: {
+        brand: string;
+        code?: string;
+        hex: string;
+        id: string;
+        libraryId: string;
+        name: string;
+    };
+    source: OpenEnum<"composed" | "family" | "hex" | "name" | "reference" | "semantic">;
+} | {
+    kind: "unresolved";
+    input: string;
+    reason: OpenEnum<"ambiguous-modifier" | "contradictory-modifiers" | "empty-range" | "unknown-term" | "unrepresentable-color" | "unsupported-base">;
+    terms: string[];
+};
+type SelectedTarget = OKLab & {
+    hasSelection: true;
+    label: string;
+    previewColors: string[];
+};
+/** The color a search matches against, by kind of selection. */
+export type MatchTarget = {
+    type: "none";
+    hasSelection: false;
+} | (SelectedTarget & {
+    type: "oklab";
+}) | (SelectedTarget & {
+    type: "palette";
+    colors: {
+        hex: string;
+        oklab: OKLab;
+    }[];
+    logic: OpenEnum<"all" | "any">;
+}) | (SelectedTarget & {
+    type: "image";
+    colors: {
+        hex: string;
+        oklab: OKLab | null;
+        proportion: number;
+    }[];
+}) | (SelectedTarget & {
+    type: "gradient";
+    startColor: {
+        hex: string;
+        oklab: OKLab;
+    };
+    endColor: {
+        hex: string;
+        oklab: OKLab;
+    };
+}) | (SelectedTarget & {
+    type: "range";
+    representative: {
+        hex: string;
+    };
+    range: ColorRegion[];
+});
+export {};

package/color-wire-types.js

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

package/get-variant-types.d.ts

@@ -7,7 +7,7 @@
  * `__tests__/contract-parity.test.ts` keeps the mirror honest against the
  * server types.
  */
-import type { ListVariantsNotApplicable, ListVariantsSpecifications, SampleSubject } from "./list-variants-types.js";
+import type { ListVariantsNotApplicable, ListVariantsSpecifications, SampleSubject, VariantObservations } from "./list-variants-types.js";
 import type { VariantColorPalette } from "./material-block-types.js";
 /** The detail to add under `specifications`; absent, the answer is the compact item alone. */
 export type GetVariantOptions = {
@@ -15,6 +15,8 @@ export type GetVariantOptions = {
     attributes?: readonly string[];
     /** Canonical block ids, returned whole, e.g. `["acoustic"]`. */
     blocks?: readonly string[];
+    /** Observation attribute ids, e.g. `["sample_size"]`, returned under `observations` by channel. */
+    observations?: readonly string[];
     /** Add `ifc`: the IFC 4.3 manufacturer property set and classification references. */
     ifc?: boolean;
 };
@@ -98,6 +100,8 @@ export type GetVariantOutput = {
     variantLabel: string | null;
     /** Requested blocks or attributes the variant's product type does not carry. */
     notApplicable?: ListVariantsNotApplicable;
+    /** Present when `observations` was asked for and the variant has any. */
+    observations?: VariantObservations;
     /** Present when `ifc` was asked for. */
     ifc?: GetVariantIfc;
     product: {

package/index.d.ts

@@ -1,7 +1,7 @@
 export type { DiscoveryReference, DiscoveryTerms, InterpretDiscoveryTermsInput, ColorlessVariantsResult, VariantSibling, } from "./discovery-context-types.js";
 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, VariantCard, } from "./list-variants-types.js";
+export type { FilterOp, FilterTermCondition, FilterNumericCondition, FilterPresenceCondition, FilterAnyFieldCondition, FilterCondition, FilterGroups, OptionalFilterGroups, OrderByEntry, ListVariantsInclude, ListVariantsCollapse, ColorRegion, ColorRangeCondition, ListVariantsInput, ListVariantsPreference, ListVariantsSpecifications, ListVariantsNotApplicable, SampleSizeObservation, VariantObservations, 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, SearchVariantsSuggestion, SearchVariantsChoice, SearchVariantsOutput, } from "./search-variants-types.js";
 export type { ListEnumValuesOptions, EnumValueMatch, EnumValueItem, ListEnumValuesResult, } from "./list-enum-values-types.js";
@@ -27,7 +27,7 @@ export type { ColorsTransport } from "./colors-client.js";
 export type { CategoryTier, CategoryColor, CategoryColorProfile, CategoryColorProfilesResponse, ColorProfilesParams, } from "./color-profiles-types.js";
 export type { DeclaredProvenance, DeclaredAssociationSubject, DeclaredAssociation, DeclaredAssociationsResponse, AssociatedOptions, ApplicabilitySubject, ApplicabilityCoverageState, ApplicabilityCoverage, ApplicabilityFact, ApplicabilitySourceEntry, UnresolvedApplicabilityEndpoint, ApplicabilityResponse, ApplicabilityOptions, } from "./association-types.js";
 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 { VariantAssetAvailability, VariantImageRole, VariantImagePresentation, VariantImageShows, VariantImageSurfaceMm, 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 { NearestPaintsParams, NearestPaintCard, NearestPaintsHexResult, NearestPaintsOutput, } from "./nearest-paints-types.js";

package/list-variants-types.d.ts

@@ -145,6 +145,8 @@ export type ListVariantsInput = {
      * ambiguous matches are all returned rather than guessed between.
      */
     name?: string;
+    /** Observation attribute ids to add under each item's `observations`, e.g. `["sample_size"]`. */
+    observations?: string[];
     /** Rank only — never excludes. */
     optionalFilters?: OptionalFilterGroups;
     orderBy?: OrderByEntry[];
@@ -162,6 +164,23 @@ export type ListVariantsPreference = {
 };
 /** `{ [blockId]: { [attributeId]: value } }`. Null means the value is unknown. */
 export type ListVariantsSpecifications = Record<string, Record<string, unknown>>;
+/** Material Bank's printed sample size. Any field may be absent; absent is unknown, never 0. */
+export type SampleSizeObservation = {
+    /** The sample size as the channel printed it, verbatim. */
+    wording?: string;
+    /** The shorter side in millimeters. */
+    width_mm?: number;
+    /** The longer side in millimeters. */
+    length_mm?: number;
+};
+/**
+ * `{ [channel]: { [attributeId]: value } }`: the latest observation of each
+ * selected attribute for each channel (`no_channel` when none is named). An
+ * attribute with no observation is absent.
+ */
+export type VariantObservations = Record<string, {
+    sample_size?: SampleSizeObservation;
+} & Record<string, unknown>>;
 export type ListVariantsNotApplicable = {
     attributes?: string[];
     blocks?: string[];
@@ -210,6 +229,8 @@ export type ListVariantsItem = {
     /** The trimmed source variant label; null when unknown or for a paint color sample, whose own name identifies its color. Separate from surface finish, color family and derived color names. */
     variantLabel: string | null;
     notApplicable?: ListVariantsNotApplicable;
+    /** Present when `observations` was asked for and the variant has any. */
+    observations?: VariantObservations;
     preference?: ListVariantsPreference;
     product: {
         id: string;

package/material-asset-types.d.ts

@@ -20,6 +20,13 @@ export type VariantAssetAvailability = OpenEnum<"available" | "unknown" | "unava
 export type VariantImageRole = OpenEnum<"product" | "swatch" | "detail" | "scene" | "technical" | "color_chart" | "sample_collection" | "other" | "unknown">;
 /** 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 photo shows of its material, so an app can place it at real size. */
+export type VariantImageShows = OpenEnum<"sample" | "crop" | "laid_field" | "room" | "detail">;
+/** The size of the surface in an image's frame, in millimeters. */
+export type VariantImageSurfaceMm = {
+    width_mm: number;
+    height_mm: number;
+};
 /** 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" | "catalog" | "color_finish_chart" | "other" | "unknown">;
 /** Every asset kind the registry knows. */
@@ -43,10 +50,16 @@ export type VariantAssetItem = {
     /** Images only; absent when unknown. */
     imageRole?: VariantImageRole;
     kind: VariantAssetKind;
+    /** Millimeters per pixel of this file. Images only; absent when unknown. */
+    mmPerPx?: number;
     /** Not on images; absent when unknown. */
     name?: string;
     /** Images only; absent when unknown. */
     presentation?: VariantImagePresentation;
+    /** What the photo shows of the material. Images only; absent when unknown. */
+    shows?: VariantImageShows;
+    /** The surface in frame: width and height times `mmPerPx`. Images only; absent when unknown. */
+    surfaceMm?: VariantImageSurfaceMm;
     url?: string;
     /** Images only; absent when unknown. */
     width?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -16,9 +16,6 @@
       "import": "./response-schemas.js"
     }
   },
-  "dependencies": {
-    "@materialinstruments/colorscope": "14.0.1"
-  },
   "license": "Proprietary",
   "engines": {
     "node": ">=24.0.0"

package/resolve-color-types.d.ts

@@ -1,9 +1,8 @@
-import type { MatchTarget } from "@materialinstruments/colorscope/match";
 /**
  * Color-name resolution (GET `/api/v1/search/colors/resolve`): the resolved
  * color, and whether the named paint is a variant in the catalog.
  */
-import type { ColorResolution } from "@materialinstruments/colorscope/naming";
+import type { ColorResolution, MatchTarget } from "./color-wire-types.js";
 import type { VariantId } from "./identifiers.js";
 import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
 import type { OpenEnum } from "./types.js";