@instruments/materialgraph 3.0.2 → 3.2.0

package/http-transport.d.ts

@@ -1,37 +1,38 @@
 import type { RateLimit } from "./errors.js";
+import type { JsonValue } from "./json-value-types.js";
 import type { JsonOperationId, OperationResponses } from "./operation-responses.js";
 import type { SdkOperation } from "./operations.js";
 type QueryValue = string | number | boolean | undefined | null | (string | number | boolean)[];
 export type QueryParams = Record<string, QueryValue>;
-export type RequestOptions = {
+export interface RequestOptions {
     /** Required by state-changing operations that support safe retries. */
     idempotencyKey?: string;
     query?: QueryParams;
     body?: unknown;
     signal?: AbortSignal;
     pathParams?: Readonly<Record<string, string>>;
-};
+}
 /** A read, status-checked HTTP response with its parsed body. */
-export type SentResponse = {
+export interface SentResponse {
     response: Response;
     text: string;
-    parsed: unknown;
-};
-type SendInput = {
+    parsed: JsonValue | undefined;
+}
+interface SendInput {
     method: string;
     url: string;
     headers: Record<string, string>;
     /** The only bodies the SDK sends: a JSON string or a multipart `FormData`. */
     body?: string | FormData;
     signal?: AbortSignal;
-};
-export type HttpTransportOptions = {
+}
+export interface 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;
     readonly baseUrl: string;
@@ -40,7 +41,10 @@ export declare class HttpTransport {
     constructor(options: HttpTransportOptions);
     get lastRateLimit(): RateLimit | null;
     /** The bearer + JSON `Accept` headers, plus any per-request additions. */
-    authHeaders(extra?: Record<string, string>): Record<string, string>;
+    authHeaders(extra?: Record<string, string>): {
+        Accept: string;
+        Authorization: string;
+    };
     buildUrl(path: string, query?: QueryParams): string;
     /**
      * Send one request, capture rate limits, read the body, and map a non-2xx or

package/http-transport.js

@@ -6,6 +6,7 @@
  * failure surfaces as one {@link MaterialGraphError}.
  */
 import { MaterialGraphError } from "./errors.js";
+import { parseJson } from "./json.js";
 import { operationPath } from "./operations.js";
 import { parseOperationResponse } from "./parse-operation-response.js";
 const parseNumberOrNull = (value) => {
@@ -106,11 +107,11 @@ export class HttpTransport {
                 signal,
             });
         }
-        catch (cause) {
+        catch (error) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
                 callerSignal: signal,
-                cause,
+                cause: error,
             });
         }
         const rateLimit = parseRateLimit(response.headers);
@@ -119,17 +120,17 @@ export class HttpTransport {
         try {
             text = await response.text();
         }
-        catch (cause) {
+        catch (error) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
                 callerSignal: signal,
-                cause,
+                cause: error,
             });
         }
         let parsed;
         if (text.length > 0) {
             try {
-                parsed = JSON.parse(text);
+                parsed = parseJson(text);
             }
             catch {
                 parsed = text;
@@ -152,15 +153,16 @@ export class HttpTransport {
     async requestJson(sdkOperation, options = {}) {
         const url = this.buildUrl(operationPath(sdkOperation, options.pathParams), options.query);
         const hasBody = options.body !== undefined;
+        const extraHeaders = {};
+        if (hasBody) {
+            extraHeaders["Content-Type"] = "application/json";
+        }
+        if (options.idempotencyKey !== undefined && options.idempotencyKey !== "") {
+            extraHeaders["Idempotency-Key"] = options.idempotencyKey;
+        }
         const { parsed } = await this.send({
             body: hasBody ? JSON.stringify(options.body) : undefined,
-            headers: this.authHeaders({
-                ...(hasBody ? { "Content-Type": "application/json" } : {}),
-                ...(options.idempotencyKey !== undefined &&
-                    options.idempotencyKey !== ""
-                    ? { "Idempotency-Key": options.idempotencyKey }
-                    : {}),
-            }),
+            headers: this.authHeaders(extraHeaders),
             method: sdkOperation.method,
             signal: options.signal,
             url,

package/image-reference-types.d.ts

@@ -6,7 +6,7 @@
  * or an existing variant's own image. Exactly one field is set per call; the
  * server refuses more than one.
  */
-export type ImageReferenceInput = {
+export interface ImageReferenceInput {
     /** Catalog asset id. */
     assetId?: string;
     /** Upload id (`smf_...`) from source-material. */
@@ -15,4 +15,4 @@ export type ImageReferenceInput = {
     url?: string;
     /** Variant whose image to use. */
     variantId?: string;
-};
+}

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/json.d.ts

@@ -0,0 +1,18 @@
+import type { JsonValue } from "./json-value-types.js";
+/** A JSON object: string keys, JSON values. */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type JsonKind = "array" | "boolean" | "null" | "number" | "object" | "string" | "undefined";
+/** What a parsed JSON value is, or `undefined` for a key an object lacks. */
+export declare const jsonKind: (value: JsonValue | undefined) => JsonKind;
+export declare const isJsonObject: (value: JsonValue | undefined) => value is JsonObject;
+export declare const isJsonString: (value: JsonValue | undefined) => value is string;
+export declare const isJsonNumber: (value: JsonValue | undefined) => value is number;
+/** Parses JSON text; throws on text that is not JSON. */
+export declare const parseJson: (text: string) => JsonValue;
+/**
+ * Reads a value of unknown origin as the JSON it would serialize to. A value
+ * JSON cannot represent, such as a `bigint`, reads as absent.
+ */
+export declare const toJsonValue: (value: unknown) => JsonValue | undefined;

package/json.js

@@ -0,0 +1,36 @@
+/** What a parsed JSON value is, or `undefined` for a key an object lacks. */
+export const jsonKind = (value) => {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    // oxlint-disable-next-line anti-slop/no-runtime-typeof -- This is the one place a parsed JSON value is classified; every other check calls it.
+    const kind = typeof value;
+    if (kind === "boolean" || kind === "number" || kind === "string") {
+        return kind;
+    }
+    return kind === "undefined" ? "undefined" : "object";
+};
+export const isJsonObject = (value) => jsonKind(value) === "object";
+export const isJsonString = (value) => jsonKind(value) === "string";
+export const isJsonNumber = (value) => jsonKind(value) === "number";
+/** Parses JSON text; throws on text that is not JSON. */
+export const parseJson = (text) => 
+// oxlint-disable-next-line typescript/no-unsafe-return -- `JSON.parse` returns exactly the values `JsonValue` names.
+JSON.parse(text);
+/**
+ * Reads a value of unknown origin as the JSON it would serialize to. A value
+ * JSON cannot represent, such as a `bigint`, reads as absent.
+ */
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- A published caller may pass any body; this is where it becomes JSON.
+export const toJsonValue = (value) => {
+    try {
+        const text = JSON.stringify(value);
+        return text === undefined ? undefined : parseJson(text);
+    }
+    catch {
+        return undefined;
+    }
+};

package/list-enum-values-types.d.ts

@@ -8,7 +8,7 @@
  */
 import type { OpenEnum } from "./types.js";
 /** Options for `listEnumValues()` (GET `/api/v1/catalog/enum-values`). */
-export type ListEnumValuesOptions = {
+export interface ListEnumValuesOptions {
     /**
      * A value dictionary id, from a `listAttributes()` item's `dictionaryId`.
      * Required without a `query`; with a `query`, omit it to search every
@@ -21,9 +21,9 @@ export type ListEnumValuesOptions = {
     limit?: number;
     /** `pageInfo.endCursor` from the previous page, with the same query and dictionary. */
     cursor?: string;
-};
+}
 /** How an item was found. A distance or similarity compares only within one method. */
-export type EnumValueMatch = {
+export interface EnumValueMatch {
     method: OpenEnum<"exact" | "alias" | "fuzzy" | "vector">;
     /** The id, label or alias that matched, or null for a match by meaning. */
     matchedText: string | null;
@@ -33,9 +33,9 @@ export type EnumValueMatch = {
     resolvedFrom?: string;
     /** Cosine similarity, 1 best. */
     similarity?: number;
-};
+}
 /** One allowed value of a dictionary. */
-export type EnumValueItem = {
+export interface EnumValueItem {
     /** The attributes this value can filter `listVariants()` on; empty when it cannot be filtered on. */
     attributeIds: string[];
     /** The taxonomy's definition when the value resolves to a canonical concept, otherwise null. */
@@ -46,8 +46,8 @@ export type EnumValueItem = {
     match?: EnumValueMatch;
     /** The bare term id `listVariants()` accepts for any of `attributeIds`. */
     valueId: string;
-};
-export type ListEnumValuesResult = {
+}
+export interface ListEnumValuesResult {
     /** The dictionary the page was read from; null when a query searched every dictionary. */
     dictionaryId: string | null;
     items: EnumValueItem[];
@@ -55,4 +55,4 @@ export type ListEnumValuesResult = {
         endCursor: string | null;
         hasNextPage: boolean;
     };
-};
+}

package/list-sampled-together-pairs-types.d.ts

@@ -5,15 +5,15 @@
  * `packages/sampling/src/sampled-together-pairs.ts`; this SDK has no runtime
  * dependency on `@materialgraph/sampling`, so the shapes are copied here.
  */
-export type ListSampledTogetherPairsInput = {
+export interface ListSampledTogetherPairsInput {
     /** `nextCursor` from the previous page. */
     cursor?: string;
     /** Pairs per page, at most 5,000. Default 2,000. */
     limit?: number;
     /** Smallest project count a pair needs. Default 3. */
     minProjects?: number;
-};
-export type SampledTogetherPair = {
+}
+export interface SampledTogetherPair {
     a: string;
     b: string;
     /** Projects that sampled both. */
@@ -25,8 +25,8 @@ export type SampledTogetherPair = {
     /** Each side's own sampled project total; null when unknown. */
     aProjects: number | null;
     bProjects: number | null;
-};
-export type ListSampledTogetherPairsOutput = {
+}
+export interface ListSampledTogetherPairsOutput {
     window: "trailing_36mo";
     signal: "sampled";
     windowStart: string | null;
@@ -36,4 +36,4 @@ export type ListSampledTogetherPairsOutput = {
     projectTotalsWindowEnd: string | null;
     pairs: SampledTogetherPair[];
     nextCursor: string | null;
-};
+}

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

@@ -9,7 +9,7 @@ import type { FilterGroups } from "./list-variants-types.js";
  * `contract-parity.test.ts` keeps them honest.
  */
 import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
-export type ListVariantFacetsInput = {
+export interface ListVariantFacetsInput {
     /** 1–10 facetable attribute ids, or `brand`. Find attribute ids with `listAttributes()`. */
     attributeIds: string[];
     /** The same kind-grouped filter tree `listVariants()` takes. */
@@ -18,20 +18,20 @@ export type ListVariantFacetsInput = {
     filters?: FilterGroups;
     /** Top values per categorical or boolean facet, 1–50. Defaults to 10. */
     valuesPerFacet?: number;
-};
-export type VariantFacetValue = {
+}
+export interface VariantFacetValue {
     /** The canonical value `listVariants()`' `filters` accepts for this attribute. */
     value: string;
     label: string;
     /** Distinct eligible variants under the supplied filters carrying this value. */
     variantCount: number;
-};
-type VariantFacetBase = {
+}
+interface VariantFacetBase {
     attributeId: string;
     name: string;
     /** Eligible variants recording no accepted value: unknown, never false or zero. */
     missingVariantCount: number;
-};
+}
 export type CategoricalVariantFacet = VariantFacetBase & {
     kind: "categorical";
     values: VariantFacetValue[];
@@ -51,10 +51,10 @@ export type NumericVariantFacet = VariantFacetBase & {
     unitId: string | null;
 };
 export type VariantFacet = CategoricalVariantFacet | BooleanVariantFacet | NumericVariantFacet;
-export type ListVariantFacetsOutput = {
+export interface ListVariantFacetsOutput {
     /** Eligible variants matching every hard condition: the denominator of every count. */
     matchedVariantCount: number;
     /** One per requested attribute, in request order. */
     facets: VariantFacet[];
-};
+}
 export {};

package/list-variants-types.d.ts

@@ -11,7 +11,7 @@
  */
 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 = {
+export interface FilterTermCondition {
     field: string;
     op: "in" | "all" | "not_in";
     /**
@@ -26,23 +26,23 @@ export type FilterTermCondition = {
      */
     unstated?: "pass";
     values: string[];
-};
-export type FilterNumericCondition = {
+}
+export interface FilterNumericCondition {
     field: string;
     op: "eq" | "gt" | "gte" | "lt" | "lte";
     value: number;
-};
-export type FilterPresenceCondition = {
+}
+export interface FilterPresenceCondition {
     field: string;
     op: "exists" | "missing";
-};
+}
 /**
  * A term stated under ANY of `fields` (2–8 distinct term attributes), for a
  * concept stored under several of them. `in`: at least one of `values` under
  * at least one field. `not_in`: at least one field stated at all, and none of
  * `values` under any field.
  */
-export type FilterAnyFieldCondition = {
+export interface FilterAnyFieldCondition {
     fields: string[];
     op: "in" | "not_in";
     /**
@@ -57,7 +57,7 @@ export type FilterAnyFieldCondition = {
      */
     unstated?: "pass";
     values: string[];
-};
+}
 /**
  * One filter condition, whichever of the four fully-required shapes. No
  * `unit` key (a numeric value is in the attribute's own canonical unit).
@@ -70,14 +70,14 @@ export type FilterCondition = FilterTermCondition | FilterNumericCondition | Fil
  * fields. Send only the arrays you need; an omitted or empty array carries no
  * conditions.
  */
-export type FilterGroups = {
+export interface FilterGroups {
     terms?: FilterTermCondition[];
     numbers?: FilterNumericCondition[];
     presence?: FilterPresenceCondition[];
     anyField?: FilterAnyFieldCondition[];
-};
+}
 /** `optionalFilters`: the same kind-grouped shape as `filters` but for `unstated`, with every entry also carrying a required `weight` (1–10). Ranks matched items; never excludes. */
-export type OptionalFilterGroups = {
+export interface OptionalFilterGroups {
     terms?: (Omit<FilterTermCondition, "unstated"> & {
         weight: number;
     })[];
@@ -90,33 +90,33 @@ export type OptionalFilterGroups = {
     anyField?: (Omit<FilterAnyFieldCondition, "unstated"> & {
         weight: number;
     })[];
-};
-export type OrderByEntry = {
+}
+export interface OrderByEntry {
     direction: "asc" | "desc";
     /** A numeric attribute id. */
     field: string;
-};
+}
 export type ListVariantsInclude = "image" | "url";
 export type ListVariantsCollapse = "product" | "colorway";
 /** A region in OKLCh: lightness and chroma as bounds, hue an arc in degrees that wraps when its start is past its end, null for any hue. */
-export type ColorRegion = {
+export interface ColorRegion {
     chroma: [number, number];
     hue: [number, number] | null;
     lightness: [number, number];
-};
+}
 /**
  * A measured-color condition. `in` keeps a variant with a large swatch inside
  * `range`; `not_in` leaves those out and lets a variant with no measured
  * color pass. `preferred` only orders and never narrows.
  */
-export type ColorRangeCondition = {
+export interface ColorRangeCondition {
     /** The color's own point in the region, `#rrggbb`; it orders matches, nearest first. */
     hex: string;
     intent?: "required" | "preferred";
     op: "in" | "not_in";
     range: ColorRegion;
-};
-export type ListVariantsInput = {
+}
+export interface ListVariantsInput {
     /** Attribute ids to project under each item's `specifications`. */
     attributes?: string[];
     /**
@@ -145,27 +145,55 @@ 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[];
     /** Words each variant must name in its text, inside the filters. */
     words?: string[];
-};
+}
 /**
  * `score` sums the weights of the matched `optionalFilters`; `matched` lists
  * their positions in the flattened terms-then-numbers-then-presence-then-anyField order
  * the server reads `optionalFilters` in, not the caller's own array shape.
+ * `looks` says how the row met each look it matched (named for it, its value
+ * stated, its words in the description) and by which words; `photo`, that its
+ * photograph looks like the look.
  */
-export type ListVariantsPreference = {
+export interface ListVariantsPreference {
+    looks?: {
+        by: ("named" | "stated" | "described")[];
+        index: number;
+        words?: string;
+    }[];
     matched: number[];
+    photo?: true;
     score: number;
-};
+}
 /** `{ [blockId]: { [attributeId]: value } }`. Null means the value is unknown. */
 export type ListVariantsSpecifications = Record<string, Record<string, unknown>>;
-export type ListVariantsNotApplicable = {
+/** Material Bank's printed sample size. Any field may be absent; absent is unknown, never 0. */
+export interface 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 interface ListVariantsNotApplicable {
     attributes?: string[];
     blocks?: string[];
-};
+}
 /** What a sample represents, independently of its specification type. */
 export type SampleSubject = "material" | "paint_color_sample" | "unknown" | "conflict";
 /**
@@ -173,7 +201,7 @@ export type SampleSubject = "material" | "paint_color_sample" | "unknown" | "con
  * and brand page only when requested (`include`) and selected attributes
  * under `specifications`. Leaner than `get_variant`'s item on purpose.
  */
-export type ListVariantsItem = {
+export interface ListVariantsItem {
     category: {
         id: string;
         name: string;
@@ -210,6 +238,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;
@@ -223,7 +253,7 @@ 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:
@@ -233,7 +263,7 @@ 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 = {
+export interface ListVariantsOutput {
     /** 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[];
@@ -252,11 +282,11 @@ export type ListVariantsOutput = {
     unavailableVariantIds?: string[];
     /** Explicit `{field: "variant", op: "in"}` ids anywhere in `filters.terms` that name no variant at all. */
     unresolvedVariantIds?: string[];
-    /** Filtered attributes no variant in scope states at all. Present only on an empty first page, so its absence means the empty page is a genuine no-match. */
+    /** Filter fields no variant in scope states at all. Present only on an empty first page, so its absence means the empty page is a genuine no-match. */
     unstated?: string[];
     /** Each requested word and whether any variant in scope names it. */
     words?: {
         matched: boolean;
         word: string;
     }[];
-};
+}