@instruments/materialgraph 3.0.2 → 3.2.0

package/errors.d.ts

@@ -1,12 +1,11 @@
-/** Error and rate-limit contracts for the retry-free MaterialGraph SDK. */
 export type MaterialGraphErrorKind = "problem" | "simple" | "network" | "timeout" | "aborted" | "rate_limited" | "unexpected";
 export type SanitizedErrorValue = null | boolean | number | string | SanitizedErrorValue[] | SanitizedIssue;
 /** A bounded, recursively sanitized validation-issue record. */
-export type SanitizedIssue = {
+export interface SanitizedIssue {
     [key: string]: SanitizedErrorValue;
-};
+}
 /** Normalized RFC 7807 body. Unknown response fields are intentionally discarded. */
-export type ProblemDetail = {
+export interface ProblemDetail {
     type: string;
     title: string;
     status: number;
@@ -23,27 +22,27 @@ export type ProblemDetail = {
      * not carry them. See {@link MATERIALGRAPH_PROBLEM_EXTENSIONS}.
      */
     readonly [extension: string]: unknown;
-};
+}
 /** Normalized residual `{ error }` body. Unknown response fields are discarded. */
-export type SimpleErrorBody = {
+export interface SimpleErrorBody {
     /** The vector and variant routes' machine-readable code, when the body is `{ code, message }`. */
     code?: string;
     error: string;
     issues?: SanitizedIssue[];
-};
+}
 /** Parsed `X-RateLimit-*` / `Retry-After` headers. `null` means absent. */
-export type RateLimit = {
+export interface RateLimit {
     limit: number | null;
     remaining: number | null;
     reset: number | null;
     retryAfter: number | null;
-};
-export type MaterialGraphRequestMetadata = {
+}
+export interface MaterialGraphRequestMetadata {
     method: string;
     origin: string;
     path: string;
-};
-export type MaterialGraphErrorInit = {
+}
+export interface MaterialGraphErrorInit {
     kind: MaterialGraphErrorKind;
     status?: number;
     retriable: boolean;
@@ -56,7 +55,7 @@ export type MaterialGraphErrorInit = {
     path?: string;
     /** Accepted for compatibility but deliberately never retained on the public error. */
     cause?: unknown;
-};
+}
 type ResponseErrorInput = {
     status: number;
     body: unknown;

package/errors.js

@@ -1,4 +1,5 @@
 /** Error and rate-limit contracts for the retry-free MaterialGraph SDK. */
+import { isJsonNumber, isJsonObject, isJsonString, toJsonValue, } from "./json.js";
 const RETRIABLE_STATUS = new Set([502, 503, 504]);
 /**
  * MaterialGraph's documented problem EXTENSION members — the only non-standard
@@ -45,7 +46,6 @@ const MAX_UNEXPECTED_TEXT = 768;
 const MAX_EXTENSION_DEPTH = 8;
 const MAX_EXTENSION_ITEMS = 100;
 const MAX_EXTENSION_STRING = 1024;
-const isRecord = (value) => typeof value === "object" && value !== null;
 const redact = (text, secrets) => {
     let sanitized = text;
     for (const secret of secrets) {
@@ -67,35 +67,35 @@ const requestMetadata = (input) => ({
     origin: input.origin,
     path: input.path,
 });
-const sanitizeValue = (value, secrets, depth = 0) => {
-    if (depth >= MAX_EXTENSION_DEPTH) {
-        return undefined;
-    }
-    if (value === null || typeof value === "boolean") {
-        return value;
-    }
-    if (typeof value === "number") {
-        return Number.isFinite(value) ? value : undefined;
-    }
-    if (typeof value === "string") {
-        return safeString(value, secrets);
-    }
-    if (Array.isArray(value)) {
-        return value
-            .slice(0, MAX_EXTENSION_ITEMS)
-            .map((item) => sanitizeValue(item, secrets, depth + 1))
-            .filter((item) => item !== undefined);
-    }
-    if (!isRecord(value)) {
-        return undefined;
-    }
-    return sanitizeRecord(value, secrets, depth);
-};
-const sanitizeRecord = (value, secrets, depth) => {
+/** Redact, cap and drop non-JSON from one object, at most {@link MAX_EXTENSION_DEPTH} levels deep. */
+const sanitizeObject = (value, secrets, depth) => {
+    const sanitizeItem = (item, itemDepth) => {
+        if (itemDepth >= MAX_EXTENSION_DEPTH) {
+            return undefined;
+        }
+        if (item === null || item === true || item === false) {
+            return item;
+        }
+        if (isJsonNumber(item)) {
+            return Number.isFinite(item) ? item : undefined;
+        }
+        if (isJsonString(item)) {
+            return safeString(item, secrets);
+        }
+        if (Array.isArray(item)) {
+            return item
+                .slice(0, MAX_EXTENSION_ITEMS)
+                .map((child) => sanitizeItem(child, itemDepth + 1))
+                .filter((child) => child !== undefined);
+        }
+        return isJsonObject(item)
+            ? sanitizeObject(item, secrets, itemDepth)
+            : undefined;
+    };
     const entries = Object.entries(value)
         .slice(0, MAX_EXTENSION_ITEMS)
         .flatMap(([key, item]) => {
-        const sanitized = sanitizeValue(item, secrets, depth + 1);
+        const sanitized = sanitizeItem(item, depth + 1);
         return sanitized === undefined
             ? []
             : [[safeString(key, secrets), sanitized]];
@@ -108,12 +108,11 @@ const sanitizeIssues = (value, secrets) => {
     }
     return value
         .slice(0, MAX_EXTENSION_ITEMS)
-        .filter((issue) => isRecord(issue) && !Array.isArray(issue))
-        .map((issue) => sanitizeRecord(issue, secrets, 0));
+        .filter(isJsonObject)
+        .map((issue) => sanitizeObject(issue, secrets, 0));
 };
 const sanitizeSuggestions = (value, secrets) => {
-    if (!Array.isArray(value) ||
-        !value.every((suggestion) => typeof suggestion === "string")) {
+    if (!Array.isArray(value) || !value.every(isJsonString)) {
         return undefined;
     }
     return value
@@ -121,62 +120,72 @@ const sanitizeSuggestions = (value, secrets) => {
         .map((suggestion) => safeString(suggestion, secrets));
 };
 const normalizeProblem = (body, secrets) => {
-    if (!isRecord(body) ||
-        typeof body.type !== "string" ||
-        typeof body.title !== "string" ||
-        typeof body.status !== "number" ||
-        typeof body.detail !== "string" ||
-        typeof body.is_retriable !== "boolean" ||
-        typeof body.trace_id !== "string" ||
-        (body.instance !== undefined && typeof body.instance !== "string")) {
+    if (!isJsonObject(body)) {
+        return undefined;
+    }
+    const { detail, doc_uri: docUri, instance, is_retriable: retriable, status, title, trace_id: traceId, type, } = body;
+    if (!isJsonString(type) ||
+        !isJsonString(title) ||
+        !isJsonNumber(status) ||
+        !isJsonString(detail) ||
+        (retriable !== true && retriable !== false) ||
+        !isJsonString(traceId) ||
+        (instance !== undefined && !isJsonString(instance))) {
         return undefined;
     }
-    const suggestions = sanitizeSuggestions(body.suggestions, secrets);
-    const issues = sanitizeIssues(body.issues, secrets);
     // Extensions FIRST so a malformed one can never shadow a standard member
-    // below. `sanitizeRecord` is the existing redaction and depth/item caps —
+    // below. `sanitizeObject` is the existing redaction and depth/item caps —
     // this is that machinery finally being reached, not a second sanitizer.
-    const extensions = sanitizeRecord(Object.fromEntries(Object.entries(body).filter(([key]) => PROBLEM_EXTENSION_KEYS.has(key))), secrets, 0);
-    return {
+    const extensions = sanitizeObject(Object.fromEntries(Object.entries(body).filter(([key]) => PROBLEM_EXTENSION_KEYS.has(key))), secrets, 0);
+    const problem = {
         ...extensions,
-        type: safeString(body.type, secrets),
-        title: safeString(body.title, secrets),
-        status: body.status,
-        detail: safeString(body.detail, secrets),
-        ...(body.instance === undefined
-            ? {}
-            : { instance: safeString(body.instance, secrets) }),
-        is_retriable: body.is_retriable,
-        trace_id: safeString(body.trace_id, secrets),
-        ...(suggestions === undefined ? {} : { suggestions }),
-        ...(typeof body.doc_uri === "string"
-            ? { doc_uri: safeString(body.doc_uri, secrets) }
-            : {}),
-        ...(issues === undefined ? {} : { issues }),
+        detail: safeString(detail, secrets),
+        is_retriable: retriable,
+        status,
+        title: safeString(title, secrets),
+        trace_id: safeString(traceId, secrets),
+        type: safeString(type, secrets),
     };
+    if (instance !== undefined) {
+        problem.instance = safeString(instance, secrets);
+    }
+    const suggestions = sanitizeSuggestions(body.suggestions, secrets);
+    if (suggestions !== undefined) {
+        problem.suggestions = suggestions;
+    }
+    if (isJsonString(docUri)) {
+        problem.doc_uri = safeString(docUri, secrets);
+    }
+    const issues = sanitizeIssues(body.issues, secrets);
+    if (issues !== undefined) {
+        problem.issues = issues;
+    }
+    return problem;
 };
 const normalizeSimple = (body, secrets) => {
-    if (!isRecord(body)) {
+    if (!isJsonObject(body)) {
         return undefined;
     }
-    const issues = sanitizeIssues(body.issues, secrets);
+    const { code, error, message } = body;
+    let simple;
     // `{ 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 (!isJsonString(error) && isJsonString(code) && isJsonString(message)) {
+        simple = {
+            code: safeString(code, secrets),
+            error: safeString(message, secrets),
         };
     }
-    if (typeof body.error !== "string") {
+    else if (isJsonString(error)) {
+        simple = { error: safeString(error, secrets) };
+    }
+    else {
         return undefined;
     }
-    return {
-        error: safeString(body.error, secrets),
-        ...(issues === undefined ? {} : { issues }),
-    };
+    const issues = sanitizeIssues(body.issues, secrets);
+    if (issues !== undefined) {
+        simple.issues = issues;
+    }
+    return simple;
 };
 const unexpectedMessage = (status, responseText, secrets) => {
     const sanitized = redact(responseText, secrets)
@@ -251,8 +260,9 @@ export class MaterialGraphError extends Error {
     }
     static fromResponse(input) {
         const secrets = secretVariants(input.apiKey, input.queryValues);
-        const problem = normalizeProblem(input.body, secrets);
-        const simple = problem === undefined ? normalizeSimple(input.body, secrets) : undefined;
+        const body = toJsonValue(input.body);
+        const problem = normalizeProblem(body, secrets);
+        const simple = problem === undefined ? normalizeSimple(body, secrets) : undefined;
         const retriable = RETRIABLE_STATUS.has(input.status);
         const metadata = requestMetadata(input);
         if (input.status === 429) {

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

@@ -12,7 +12,7 @@
 /** The closed sector vocabulary co-specification evidence is tagged with. */
 export type SampledTogetherProjectType = "Workplace" | "Residential" | "Institution Education" | "Hospitality: Hotel" | "Mixed-Use & Multi-Unit Residential" | "Healthcare" | "Hospitality: Restaurant" | "Government" | "Senior Living" | "Retail" | "Other" | "Sports Entertainment" | "Wellness" | "Medical Dental" | "Aviation" | "Industrial" | "Tech" | "Transportation" | "Single Family" | "Condominium Cooperative" | "Marine" | "Power & Energy" | "University Design Program: Interior Design" | "Non-Billable" | "University Design Program: Interior Architecture" | "University Design Program: Architecture" | "Historic Preservation";
 /** At least one of `variantIds` and `materials`, at most twelve together. */
-export type FindSampledTogetherInput = {
+export interface FindSampledTogetherInput {
     /** Optional row fields: image adds imageUrl, color adds swatches. */
     include?: ("image" | "color")[];
     /** Materials to return, default 20, at most 100. */
@@ -23,8 +23,8 @@ export type FindSampledTogetherInput = {
     projectType?: SampledTogetherProjectType;
     /** Variants to find sampled-together materials for. */
     variantIds?: string[];
-};
-export type FindSampledTogetherRow = {
+}
+export interface FindSampledTogetherRow {
     brand: string;
     /** Palette likeness to the seeds. Present with `include: ["color"]`; never reorders. */
     colorFit?: number | null;
@@ -49,8 +49,8 @@ export type FindSampledTogetherRow = {
     /** The trimmed source variant label; null when unknown or for a paint color sample. Separate from surface finish, color family and derived color names. */
     variantLabel: string | null;
     variantName: string | null;
-};
-export type FindSampledTogetherOutput = {
+}
+export interface FindSampledTogetherOutput {
     /** Other brands first; within each, product type groups in turn, each group best first (seeds matched, then lift weighted by projects); one row per product. */
     sampledTogether: FindSampledTogetherRow[];
     /** The seeds as resolved, so a caller sees what a name became. */
@@ -71,4 +71,4 @@ export type FindSampledTogetherOutput = {
     excludedBySearchCatalogSubset?: string[];
     /** References that matched no variant. */
     unresolved: string[];
-};
+}

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

@@ -15,7 +15,7 @@ import type { ImageReferenceInput } from "./image-reference-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 = {
+export interface ColorConditionInput {
     /** Name, code or hex (e.g. "sage green"). */
     color?: string;
     /** Must be the swatch's largest color. */
@@ -25,8 +25,8 @@ export type ColorConditionInput = {
     share?: number;
     /** Maximum share, e.g. an accent. */
     shareMax?: number;
-};
-export type FindVariantsByColorInput = {
+}
+export interface FindVariantsByColorInput {
     /** Brand slugs or names to filter to. */
     brands?: string[];
     /** One entry per color (exactly one for rerank). */
@@ -45,8 +45,8 @@ export type FindVariantsByColorInput = {
     targetVariantId?: string;
     /** Ids to reorder by color (rerank). */
     variantIds?: string[];
-};
-export type ColorConditionReceipt = {
+}
+export interface ColorConditionReceipt {
     /** CIEDE2000 difference to the assigned settled swatch. Never a probability. */
     distance: number;
     hex: string;
@@ -56,8 +56,8 @@ export type ColorConditionReceipt = {
     proportion: number;
     /** Requested share used for ColorVec retrieval, palette only; null otherwise. */
     target: number | null;
-};
-export type PaintCatalogVariant = {
+}
+export interface PaintCatalogVariant {
     brand: string;
     color: string | null;
     imageUrl: string | null;
@@ -65,8 +65,8 @@ export type PaintCatalogVariant = {
     product: string;
     variantId: string;
     variantName: string | null;
-};
-export type ResolvedColor = {
+}
+export interface ResolvedColor {
     /** Other meanings of the same words, offered: ColorScope's color when a paint's exact name led. */
     alternatives?: ColorAlternative[];
     catalogVariant: PaintCatalogVariant | null;
@@ -76,21 +76,21 @@ export type ResolvedColor = {
     kind: "point" | "region";
     /** Image-extracted or stored target-variant swatch share; else null. */
     share: number | null;
-};
-export type ColorAlternative = {
+}
+export interface ColorAlternative {
     code?: string;
     hex: string;
     libraryId: string;
     libraryName: string;
     name: string;
     query: string;
-};
-export type UnresolvedColor = {
+}
+export interface UnresolvedColor {
     alternatives: ColorAlternative[];
     index: number;
     input: string | null;
-};
-export type ColorVariantMatch = {
+}
+export interface ColorVariantMatch {
     /** The trimmed source variant label; null when unknown or for a paint color sample. Separate from surface finish, color family and derived color names. */
     variantLabel: string | null;
     productType: {
@@ -116,8 +116,8 @@ export type ColorVariantMatch = {
     productId: string;
     variantId: string;
     variantName: string;
-};
-export type ColorPageInfo = {
+}
+export interface ColorPageInfo {
     endCursor: string | null;
     hasNextPage: boolean;
     /**
@@ -128,15 +128,15 @@ export type ColorPageInfo = {
      * the page where paging stops at the pool's 400 cap.
      */
     poolTruncated: boolean;
-};
-type ContainsOrPaletteResult = {
+}
+interface ContainsOrPaletteResult {
     /** Color-matched candidates dropped by `list_variants`' hard filters or eligibility. */
     gatedOut: number;
     matches: ColorVariantMatch[];
     pageInfo: ColorPageInfo;
     resolvedColors: ResolvedColor[];
     unresolvedColors: UnresolvedColor[];
-};
+}
 export type FindVariantsByColorContainsResult = ContainsOrPaletteResult & {
     mode: "contains";
 };
@@ -144,7 +144,7 @@ export type FindVariantsByColorPaletteResult = ContainsOrPaletteResult & {
     mode: "palette";
 };
 /** `reference.candidates`/`reference.seed`'s shape — mirrors `compare-color-similarity.ts`'s own seed, unlike `matches[]` below. */
-export type ColorRankedSeed = {
+export interface ColorRankedSeed {
     brand: string;
     brandSlug: string;
     color: string | null;
@@ -155,9 +155,9 @@ export type ColorRankedSeed = {
     variantId: string;
     /** The variant's own name — paint colorway names live here (label contract). */
     variantName: string | null;
-};
+}
 /** RERANK's own card — the same shape `ColorVariantMatch` above (`brandId`, `code`), plus its perceptual distance. */
-export type ColorRankMatch = {
+export interface ColorRankMatch {
     /** The trimmed source variant label; null when unknown or for a paint color sample. Separate from surface finish, color family and derived color names. */
     variantLabel: string | null;
     brand: string;
@@ -171,13 +171,13 @@ export type ColorRankMatch = {
     productId: string;
     variantId: string;
     variantName: string | null;
-};
-export type ResolvedColorReference = {
+}
+export interface ResolvedColorReference {
     hex: string;
     name: string | null;
     ref: string;
-};
-export type CompareColorSimilarityReference = {
+}
+export interface CompareColorSimilarityReference {
     /** Best-per-brand candidates when `resolution === "ambiguous"`; empty otherwise. */
     candidates: ColorRankedSeed[];
     /** The resolved color when the reference was a `color`, else null. */
@@ -197,8 +197,8 @@ export type CompareColorSimilarityReference = {
     resolution: "resolved" | "ambiguous";
     /** The resolved seed when the reference was a `material`/`variantId`, else null. */
     seed: ColorRankedSeed | null;
-};
-export type FindVariantsByColorRerankResult = {
+}
+export interface FindVariantsByColorRerankResult {
     /** Present ONLY when the request narrowed it. ABSENT means the whole graph. */
     searchCatalogSubset?: SearchCatalogSubsetReceipt;
     /** Real variant ids outside `searchCatalogSubset` or the materials catalog. Present when a scope narrowed or any was excluded. */
@@ -212,6 +212,6 @@ export type FindVariantsByColorRerankResult = {
     resolvedColors: ResolvedColor[];
     /** Candidate ids that did not resolve to any variant. */
     unresolved: string[];
-};
+}
 export type FindVariantsByColorOutput = FindVariantsByColorContainsResult | FindVariantsByColorPaletteResult | FindVariantsByColorRerankResult;
 export {};

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

@@ -12,14 +12,14 @@ 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 = {
+export interface FindVariantsByVectorQuery {
     /** 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;
-};
-export type FindVariantsByVectorInput = {
+}
+export interface FindVariantsByVectorInput {
     /** Attribute or block ids to add. */
     attributes?: string[];
     /** Variant ids to leave out. A seed image's own variant is always left out. */
@@ -30,26 +30,26 @@ export type FindVariantsByVectorInput = {
     query: FindVariantsByVectorQuery;
     /** Only this corpus scope. Absent or all: every variant. */
     searchCatalogSubset?: SearchCatalogSubset;
-};
+}
 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. */
     similarity: number;
 };
-export type FindVariantsByVectorReference = {
+export interface FindVariantsByVectorReference {
     id: string;
     kind: "url" | "assetId" | "variantId" | "sourceId";
-};
-export type FindVariantsByVectorScan = {
+}
+export interface FindVariantsByVectorScan {
     /** True when no further candidates match; false means more may exist. */
     exhausted: boolean;
     read: number;
     rejected: number;
     /** How filters reached the vector search. Always "metadata": every filter runs inside the kNN. */
     route: "lane" | "metadata" | "allowlist";
-};
-export type FindVariantsByVectorTimings = {
+}
+export interface FindVariantsByVectorTimings {
     embedMs: number;
     /** Time spent filtering outside the kNN. Always 0: filters run inside it. */
     filterMs: number;
@@ -57,8 +57,8 @@ export type FindVariantsByVectorTimings = {
     totalMs: number;
     vectorMs: number;
     verifyMs: number;
-};
-export type FindVariantsByVectorOutput = {
+}
+export interface FindVariantsByVectorOutput {
     /** 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[];
@@ -71,6 +71,6 @@ export type FindVariantsByVectorOutput = {
     timings: FindVariantsByVectorTimings;
     /** Explicit `{field: "variant", op: "in"}` filter ids that named no eligible variant — present only when at least one did. */
     unresolvedVariantIds?: string[];
-    /** Filtered attributes no variant in scope states at all. Present only on an empty 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 page, so its absence means the empty page is a genuine no-match. */
     unstated?: string[];
-};
+}

package/get-variant-types.d.ts

@@ -7,22 +7,24 @@
  * `__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 = {
+export interface GetVariantOptions {
     /** Canonical attribute ids, e.g. `["nrc"]`. */
     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;
-};
+}
 /**
  * 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 = {
+export interface GetVariantIfc {
     propertySets: {
         name: "Pset_ManufacturerTypeInformation";
         properties: {
@@ -39,13 +41,13 @@ export type GetVariantIfc = {
         name?: string;
         edition?: string;
     }[];
-};
+}
 /**
  * One variant: the compact identity, and `specifications` only for the
  * attributes and blocks that were asked for. Only stated values appear there:
  * an unknown value, and a block with none, is absent, never false or zero.
  */
-export type GetVariantOutput = {
+export interface GetVariantOutput {
     /** Whether this variant may appear in its Brand's catalog. Material-only lists also require Search Catalog membership. Reads by id include ineligible variants. */
     eligible: boolean;
     channels: string[];
@@ -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: {
@@ -113,4 +117,4 @@ export type GetVariantOutput = {
     };
     url: string | null;
     variantId: string;
-};
+}