@instruments/materialgraph 3.0.2 → 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/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.2",
+  "version": "3.1.0",
   "type": "module",
   "exports": {
     ".": {