@instruments/materialgraph 0.26.0 → 0.27.1

package/colours-client.d.ts

@@ -9,8 +9,8 @@ import type { SdkOperationId } from "./operations.js";
  * client facade: "how much colour does the graph hold at all" (`stats`), "what
  * colours does this category come in" (`profiles`), "what goes with these
  * colours" (`palette`), and "what moves from this colour to that one"
- * (`gradient`). `mg.codes` and `mg.browse` set the precedent for a namespace
- * when a capability is a family rather than a single verb.
+ * (`gradient`). `mg.codes` sets the precedent for a namespace when a
+ * capability is a family rather than a single verb.
  *
  * The namespace holds no transport of its own: the client hands it a bound
  * `get`/`post`, so auth, rate-limit accounting and error shaping stay in one
@@ -28,14 +28,13 @@ import type { SdkOperationId } from "./operations.js";
  *   convenience wrapper.
  * - A colour NAME rather than a hex → `mg.resolveColour(name)` first.
  * - Colour WORDS (families, moods, undertones) → `mg.colourFacets()`.
- * - Walking the corpus by lightness/vividness → `mg.browse({ sort })`.
- * - Colour as one signal among words, a seed and a mood → `mg.search(...)`.
+ * - Walking the corpus by lightness/vividness → `mg.listVariants({ orderBy })`.
+ * - Colour as one signal among words and a seed → `mg.search(...)`.
  *
  * And the honesty rule the whole lens rests on: every colour here is DERIVED
  * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
  * likeness, never a stated colour specification.
  */
-import type { PaletteCompleteInput, PaletteCompleteResponse, PaletteDiscoverInput, PaletteDiscoverResponse } from "./palette-completion-types.js";
 import type { SearchGradientInput, SearchGradientResponse, SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
 /** The client's own request primitives, handed down so this file owns no transport. */
 export type ColoursTransport = {
@@ -45,10 +44,6 @@ export type ColoursTransport = {
 export declare class ColoursClient {
     #private;
     constructor(transport: ColoursTransport);
-    /** Complete exact retained colors against a shared published interior reference. No Cart mutation. */
-    complete(input: PaletteCompleteInput, signal?: AbortSignal): Promise<PaletteCompleteResponse>;
-    /** Browse diverse published interior compositions against a version-pinned eligible catalogue. */
-    discover(input: PaletteDiscoverInput, signal?: AbortSignal): Promise<PaletteDiscoverResponse>;
     /**
      * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
      * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).

package/colours-client.js

@@ -3,14 +3,6 @@ export class ColoursClient {
     constructor(transport) {
         this.#transport = transport;
     }
-    /** Complete exact retained colors against a shared published interior reference. No Cart mutation. */
-    async complete(input, signal) {
-        return await this.#transport.post("complete_interior_palette", input, signal);
-    }
-    /** Browse diverse published interior compositions against a version-pinned eligible catalogue. */
-    async discover(input, signal) {
-        return await this.#transport.get("discover_interior_palettes", { ...input }, signal);
-    }
     /**
      * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
      * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).

package/errors.d.ts

@@ -89,7 +89,7 @@ type TransportErrorInput = {
  * member to a problem response means adding it here too, and
  * `problem-extension-parity.test.ts` fails when the two disagree.
  */
-export declare const MATERIALGRAPH_PROBLEM_EXTENSIONS: readonly ["ambiguous_brands", "brand_candidates", "content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "orderable_attributes", "populated_alternatives", "unknown_attributes", "unknown_brands", "unknown_fields", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
+export declare const MATERIALGRAPH_PROBLEM_EXTENSIONS: readonly ["ambiguous_brands", "brand_candidates", "content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "orderable_attributes", "populated_alternatives", "refused_criteria", "unknown_attributes", "unknown_brands", "unknown_fields", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
 /** The one error class thrown by all SDK transport and HTTP failures. */
 export declare class MaterialGraphError extends Error {
     readonly kind: MaterialGraphErrorKind;

package/errors.js

@@ -32,6 +32,7 @@ export const MATERIALGRAPH_PROBLEM_EXTENSIONS = [
     "missing_env",
     "orderable_attributes",
     "populated_alternatives",
+    "refused_criteria",
     "unknown_attributes",
     "unknown_brands",
     "unknown_fields",

package/identify-types.d.ts

@@ -1,67 +1,77 @@
 /**
- * Public wire types for `POST /api/v1/identify`.
+ * Public wire types for `POST /api/v1/identify` (MG-1672's `resolve_variant`
+ * contract).
  *
- * These intentionally mirror the domain-owned Zod contract rather than
- * importing it: the published SDK must carry no workspace package dependency.
+ * These intentionally mirror the domain-owned Zod contract
+ * (`@materialgraph/products/identify-contract`) rather than importing it: the
+ * published SDK must carry no workspace package dependency.
  */
-export type IdentifySelectedPageInput = {
-    url: string;
-    title?: string;
-    selectedText?: string;
-    productLabels?: string[];
-    brandLabels?: string[];
-    /** Manufacturer code visibly supplied by the selected page. */
-    manufacturerCode?: string;
-    imageUrls?: string[];
-    colourHexes?: string[];
+/**
+ * What `mg.identify()` accepts. Give `url` alone, or `code` with `brandId`
+ * (from `mg.brands()`) when there is no page to read. `labels` are product
+ * names visible on the page, sent only to tell several URL candidates apart -
+ * they never widen a search or invent an identity on their own.
+ */
+export type IdentifyVariantInput = {
+    url?: string;
+    code?: string;
+    brandId?: string;
+    labels?: string[];
 };
-export type IdentifySelectedPageSubject = {
-    kind: "variant" | "product" | "brand";
+/** One identified, placed or bounded-candidate subject. */
+export type IdentifySubject = {
+    kind: "variant" | "brand";
     id: string;
     name: string;
+    code?: string;
     brand?: {
         id: string;
         name: string;
-        slug: string;
     };
 };
-export type IdentifySelectedPageEvidence = {
-    kind: "manufacturer-url" | "brand-homepage" | "visible-identity" | "visual" | "colour";
+/** What stood behind an outcome. Exact and scoreless: never a similarity guess. */
+export type IdentifyEvidence = {
+    kind: "manufacturer-url" | "brand-homepage" | "manufacturer-code" | "visible-label";
     url?: string;
     detail: string;
 };
-type IdentifySelectedPageDataBase = {
-    receipt: {
-        submittedUrl: string;
-        normalizedUrl: string;
-        normalizationSteps: string[];
-    };
-    evidence: IdentifySelectedPageEvidence[];
+/** The submitted URL, normalised, and the steps that normalisation took. Absent for a code-only call. */
+export type IdentifyReceipt = {
+    submittedUrl: string;
+    normalizedUrl: string;
+    normalizationSteps: string[];
 };
-export type IdentifySelectedPageData = (IdentifySelectedPageDataBase & {
+type IdentifyResultBase = {
+    evidence: IdentifyEvidence[];
+    receipt?: IdentifyReceipt;
+};
+/**
+ * Why nothing was identified. Absent and empty differ: this names what was
+ * looked for and not found, never a similarity guess.
+ */
+export type IdentifyUnresolvedReason = "no-stored-url" | "no-code-match";
+/** Exact identities only - no rung carries a similarity score. */
+export type IdentifyResult = (IdentifyResultBase & {
     outcome: "identified";
-    rung: "lookup" | "disambiguate";
-    subject: IdentifySelectedPageSubject & {
+    subject: IdentifySubject & {
         kind: "variant";
     };
-}) | (IdentifySelectedPageDataBase & {
+}) | (IdentifyResultBase & {
     outcome: "placed";
-    rung: "lookup";
-    subject: IdentifySelectedPageSubject & {
-        kind: "product" | "brand";
+    subject: IdentifySubject & {
+        kind: "brand";
     };
-}) | (IdentifySelectedPageDataBase & {
+}) | (IdentifyResultBase & {
     outcome: "ambiguous";
-    rung: "lookup" | "disambiguate" | "match" | "color";
-    candidates: IdentifySelectedPageSubject[];
+    candidates: IdentifySubject[];
     truncated: boolean;
-}) | (IdentifySelectedPageDataBase & {
+}) | (IdentifyResultBase & {
     outcome: "unresolved";
-    rung?: "match" | "color";
+    reason: IdentifyUnresolvedReason;
 });
 /** The canonical callable-operation envelope returned by `identify()`. */
-export type IdentifySelectedPageResult = {
-    data: IdentifySelectedPageData;
+export type IdentifyResponse = {
+    data: IdentifyResult;
     meta: {
         operationId: "retrieval.identify";
         requestId: string;

package/identify-types.js

@@ -1,7 +1,9 @@
 /**
- * Public wire types for `POST /api/v1/identify`.
+ * Public wire types for `POST /api/v1/identify` (MG-1672's `resolve_variant`
+ * contract).
  *
- * These intentionally mirror the domain-owned Zod contract rather than
- * importing it: the published SDK must carry no workspace package dependency.
+ * These intentionally mirror the domain-owned Zod contract
+ * (`@materialgraph/products/identify-contract`) rather than importing it: the
+ * published SDK must carry no workspace package dependency.
  */
 export {};

package/index.d.ts

@@ -1,29 +1,23 @@
-export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
-export type { CompareInput, CompareTarget, CompareCell, CompareResult, CompareResponse, } from "./compare-types.js";
-export type { CorrectionJson, CorrectionSubject, CorrectionTarget, CorrectionEvidence, CreateCorrectionInput, Correction, CorrectionResponse, CorrectionsListResponse, } from "./correction-types.js";
-export type { MaterialGraphClientOptions, BrowseNamespace, ExplorationNamespace, SourceMaterialCommentsNamespace, } from "./client.js";
+export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
+export type { MaterialGraphClientOptions, SourceMaterialCommentsNamespace, } from "./client.js";
+export type * from "./list-variants-types.js";
+export type * from "./list-variant-facets-types.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
 export type * from "./identifiers.js";
-export type * from "./exploration-types.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type * from "./run-types.js";
 export type * from "./citation-types.js";
-export { VARY_AXES } from "./composition-types.js";
-export type * from "./composition-types.js";
-export type * from "./slot-pool-types.js";
+export type * from "./material-composition-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 * from "./types.js";
-export type * from "./search-collapse-types.js";
 export type * from "./search-card-types.js";
-export type * from "./match-types.js";
 export type * from "./identify-types.js";
-export type * from "./browse-types.js";
 export type * from "./catalogue-types.js";
 export type * from "./by-colour-types.js";
-export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
-export type * from "./match-stream-types.js";
+export { CategoriesClient } from "./categories-client.js";
+export type * from "./category-types.js";
 export { CodesClient } from "./codes-client.js";
 export type * from "./codes-types.js";
 export { ColoursClient } from "./colours-client.js";
@@ -31,23 +25,19 @@ export type { ColoursTransport } from "./colours-client.js";
 export type * from "./colour-aggregate-types.js";
 export type * from "./palette-search-types.js";
 export type * from "./query-understanding-types.js";
+export type * from "./match-types.js";
+export { MATCH_ERROR_REASONS, MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+export type * from "./match-stream-types.js";
 export type * from "./material-query-plan-types.js";
 export type * from "./association-types.js";
 export type * from "./brand-types.js";
-export type * from "./fan-deck-types.js";
 export type * from "./material-asset-types.js";
-export type * from "./render-assets-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
 export type * from "./taxonomy-coverage-types.js";
-export type * from "./substitute-types.js";
 export type * from "./search-refinement-types.js";
-export type * from "./search-window-types.js";
 export type * from "./attribution-types.js";
-export type * from "./match-rejection-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export type * from "./spec-types.js";
-export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";
+export { certificationProgramme, hasSpec, specTerm } from "./specifications.js";
 export type { SamplizePublicationSource, SamplizeLrvObservation, SamplizeDemand, SamplizeCollectionMembership, SamplizeCatalogueOptions, SamplizeCataloguePage, SamplizeCatalogueProduct, SamplizeHexObservation, } from "./samplize-catalogue-types.js";
-export type { PaletteCompleteInput, PaletteCompleteResponse, PaletteDiscoverInput, PaletteDiscoverResponse, } from "./palette-completion-types.js";
-export type { BrandMostSampledResponse } from "./brand-most-sampled-types.js";

package/index.js

@@ -1,10 +1,10 @@
-export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
+export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
-export { VARY_AXES } from "./composition-types.js";
 export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
-export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+export { CategoriesClient } from "./categories-client.js";
 export { CodesClient } from "./codes-client.js";
 export { ColoursClient } from "./colours-client.js";
+export { MATCH_ERROR_REASONS, MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
-export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";
+export { certificationProgramme, hasSpec, specTerm } from "./specifications.js";

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

@@ -0,0 +1,60 @@
+/**
+ * @module list-variant-facets-types
+ * @description Hand-maintained mirror of `list_variant_facets`'s (MG-2294)
+ * input and output wire shapes. The source of truth is
+ * `packages/products/src/variants/list-variant-facets.ts` (the input) and
+ * `list-variant-facets-contract.ts` (the output); this SDK has no runtime
+ * dependency on `@materialgraph/products`, so the shapes are copied here and
+ * `contract-parity.test.ts` keeps them honest.
+ */
+import type { CorpusScope } from "./corpus-scope-types.js";
+import type { FilterGroups } from "./list-variants-types.js";
+export type ListVariantFacetsInput = {
+    /** 1–10 facetable attribute ids. Find them with `listAttributes()`. */
+    attributeIds: string[];
+    /** The same kind-grouped filter tree `listVariants()` takes. */
+    /** Count only this corpus scope; absent or `all` counts every variant. */
+    corpusScope?: CorpusScope;
+    filters?: FilterGroups;
+    /** Top values per categorical or boolean facet, 1–50. Defaults to 10. */
+    valuesPerFacet?: number;
+};
+export type 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 = {
+    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[];
+    /** More observed values exist than `values` shows. */
+    hasMoreValues: boolean;
+};
+export type BooleanVariantFacet = VariantFacetBase & {
+    kind: "boolean";
+    values: VariantFacetValue[];
+    hasMoreValues: boolean;
+};
+export type NumericVariantFacet = VariantFacetBase & {
+    kind: "numeric";
+    /** Observed minimum in the attribute's canonical unit; null when no variant records a value. */
+    min: number | null;
+    max: number | null;
+    unitId: string | null;
+};
+export type VariantFacet = CategoricalVariantFacet | BooleanVariantFacet | NumericVariantFacet;
+export type 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

@@ -0,0 +1,149 @@
+/**
+ * @module list-variants-types
+ * @description Hand-maintained mirror of `list_variants`'s (MG-2222) input and
+ * output wire shapes. The source of truth is
+ * `packages/products/src/variants/variant-conditions.ts` (the filter grammar)
+ * and `packages/products/src/variants/list-variants-contract.ts` (the output),
+ * but this SDK has no RUNTIME dependency on `@materialgraph/products` (it's a
+ * devDependency only, for the parity tests in `__tests__/`), so the shapes are
+ * copied here rather than imported. `contract-parity.test.ts` keeps this
+ * mirror honest against the server types.
+ */
+import type { CorpusScope } from "./corpus-scope-types.js";
+export type FilterOp = "in" | "not_in" | "all" | "exists" | "missing" | "eq" | "gt" | "gte" | "lt" | "lte";
+export type FilterTermCondition = {
+    field: string;
+    op: "in" | "all" | "not_in";
+    values: string[];
+};
+export type FilterNumericCondition = {
+    field: string;
+    op: "eq" | "gt" | "gte" | "lt" | "lte";
+    value: number;
+};
+export type FilterPresenceCondition = {
+    field: string;
+    op: "exists" | "missing";
+};
+/**
+ * One filter condition, whichever of the three fully-required shapes. No
+ * `unit` key (a numeric value is in the attribute's own canonical unit).
+ */
+export type FilterCondition = FilterTermCondition | FilterNumericCondition | FilterPresenceCondition;
+/**
+ * `filters`: kind-grouped, not a flat list (MG-2222) — `{terms, numbers,
+ * presence}`. Every condition across all three arrays must match (AND); OR
+ * within one field is `in`. Send only the arrays you need; an omitted or
+ * empty array carries no conditions.
+ */
+export type FilterGroups = {
+    terms?: FilterTermCondition[];
+    numbers?: FilterNumericCondition[];
+    presence?: FilterPresenceCondition[];
+};
+/** `optionalFilters`: the same kind-grouped shape as `filters`, with every entry also carrying a required `weight` (1–10). Ranks matched items; never excludes. */
+export type OptionalFilterGroups = {
+    terms?: (FilterTermCondition & {
+        weight: number;
+    })[];
+    numbers?: (FilterNumericCondition & {
+        weight: number;
+    })[];
+    presence?: (FilterPresenceCondition & {
+        weight: number;
+    })[];
+};
+export type OrderByEntry = {
+    direction: "asc" | "desc";
+    /** A numeric attribute id. */
+    field: string;
+};
+export type ListVariantsInclude = "image" | "url";
+export type ListVariantsCollapse = "product";
+export type ListVariantsInput = {
+    /** Attribute ids to project under each item's `specifications`. */
+    attributes?: string[];
+    /**
+     * `product`: one row per product, its lead colourway by the page's order,
+     * with `variantCount` saying how many colourways stand behind it. The
+     * cursor pages products.
+     */
+    collapse?: ListVariantsCollapse;
+    /**
+     * Only variants in this corpus scope: the rows, the page and the cursor.
+     * Absent or `all` is every variant.
+     */
+    corpusScope?: CorpusScope;
+    cursor?: string;
+    /** Every condition, across `terms`/`numbers`/`presence`, must match. */
+    filters?: FilterGroups;
+    include?: ListVariantsInclude[];
+    /** 1–50; defaults to 10. */
+    limit?: number;
+    /**
+     * Find by name (MG-2222): every word must start a word of the product or
+     * variant name. Combines with `filters` as an additional AND condition;
+     * ambiguous matches are all returned rather than guessed between.
+     */
+    name?: string;
+    /** Rank only — never excludes. */
+    optionalFilters?: OptionalFilterGroups;
+    orderBy?: OrderByEntry[];
+};
+/**
+ * `score` sums the weights of the matched `optionalFilters`; `matched` lists
+ * their positions in the flattened terms-then-numbers-then-presence order
+ * the server reads `optionalFilters` in, not the caller's own array shape.
+ */
+export type ListVariantsPreference = {
+    matched: number[];
+    score: number;
+};
+/** `{ [blockId]: { [attributeId]: value } }`. Null means the value is unknown. */
+export type ListVariantsSpecifications = Record<string, Record<string, unknown>>;
+export type ListVariantsNotApplicable = {
+    attributes?: string[];
+    blocks?: string[];
+};
+/**
+ * One list item: the compact identity needed to pick a variant, with image
+ * and maker page only when requested (`include`) and selected attributes
+ * under `specifications`. Leaner than `get_variant`'s item on purpose.
+ */
+export type ListVariantsItem = {
+    category: string;
+    code: string | null;
+    image?: string | null;
+    maker: {
+        id: string;
+        name: string;
+    };
+    /** The variant's Material Bank SKU. Absent means none is recorded. */
+    materialBankId?: string;
+    name: string;
+    notApplicable?: ListVariantsNotApplicable;
+    preference?: ListVariantsPreference;
+    product: {
+        id: string;
+        name: string;
+    };
+    specifications?: ListVariantsSpecifications;
+    url?: string | null;
+    /**
+     * The eligible variants of this item's product, the set `listVariants`
+     * pages. Absent when none is counted.
+     */
+    variantCount?: number;
+    variantId: string;
+};
+export type ListVariantsOutput = {
+    items: ListVariantsItem[];
+    pageInfo: {
+        endCursor: string | null;
+        hasNextPage: boolean;
+    };
+    /** False: nothing from this page on meets any `optionalFilters` entry. Absent when not measured. */
+    preferenceMatchesRemain?: boolean;
+    /** Explicit `{field: "variant", op: "in"}` ids anywhere in `filters.terms` that did not resolve to an eligible variant in the requested `corpusScope`. */
+    unresolvedVariantIds?: string[];
+};

package/list-variants-types.js

@@ -0,0 +1,12 @@
+/**
+ * @module list-variants-types
+ * @description Hand-maintained mirror of `list_variants`'s (MG-2222) input and
+ * output wire shapes. The source of truth is
+ * `packages/products/src/variants/variant-conditions.ts` (the filter grammar)
+ * and `packages/products/src/variants/list-variants-contract.ts` (the output),
+ * but this SDK has no RUNTIME dependency on `@materialgraph/products` (it's a
+ * devDependency only, for the parity tests in `__tests__/`), so the shapes are
+ * copied here rather than imported. `contract-parity.test.ts` keeps this
+ * mirror honest against the server types.
+ */
+export {};

package/match-stream-types.d.ts

@@ -21,6 +21,9 @@ import type { SearchResultItem } from "./types.js";
 /** How the workflow classified the uploaded image. */
 export declare const MATCH_IMAGE_TYPES: readonly ["swatch", "installation", "flatplan"];
 export type MatchImageType = (typeof MATCH_IMAGE_TYPES)[number];
+/** Why a Match run ended on an `error` frame (MG-730). */
+export declare const MATCH_ERROR_REASONS: readonly ["upstream_unavailable", "failed"];
+export type MatchErrorReason = (typeof MATCH_ERROR_REASONS)[number];
 /** What a detected surface is FOR — the element the material would serve. */
 export declare const MATCH_MATERIAL_FUNCTIONS: readonly ["flooring", "wall_surface", "ceiling", "partition", "upholstery", "millwork", "countertop", "accent", "sample"];
 export type MatchMaterialFunction = (typeof MATCH_MATERIAL_FUNCTIONS)[number];
@@ -61,6 +64,8 @@ export type MatchDetectedSurface = {
     boundingBox: MatchBoundingBox;
     /** JPEG data-URI crop used for Match retrieval — the thumbnail to show. */
     cropDataUri?: string;
+    /** The `construction_methods` dictionary term the detector's finish names. */
+    construction?: string;
 };
 /**
  * One surface's matching state and its ranked results. The same `surface.id`
@@ -288,6 +293,14 @@ export type MatchStreamCompleteEvent = {
 export type MatchStreamErrorEvent = {
     type: "error";
     message: string;
+    /**
+     * `upstream_unavailable`: a provider (vision, embedding, vector index) could
+     * not answer, so nothing was looked at and a retry may succeed. `failed`: the
+     * run broke on something else. Absent from servers older than MG-730.
+     */
+    reason?: MatchErrorReason;
+    /** True only for `upstream_unavailable`. Absent from servers older than MG-730. */
+    retriable?: boolean;
 };
 /** One frame of the Match progress stream, discriminated by `type`. */
 export type MatchStreamEvent = MatchStreamStepEvent | MatchStreamClassifiedEvent | MatchStreamSurfacesEvent | MatchStreamSurfaceEvent | MatchStreamHeartbeatEvent | MatchStreamCompleteEvent | MatchStreamErrorEvent;

package/match-stream-types.js

@@ -4,6 +4,8 @@ export const MATCH_IMAGE_TYPES = [
     "installation",
     "flatplan",
 ];
+/** Why a Match run ended on an `error` frame (MG-730). */
+export const MATCH_ERROR_REASONS = ["upstream_unavailable", "failed"];
 /** What a detected surface is FOR — the element the material would serve. */
 export const MATCH_MATERIAL_FUNCTIONS = [
     "flooring",

package/match-stream.js

@@ -35,10 +35,9 @@
  *     objects (`createMatchNdjsonStream`), so `parse` output is not what the wire
  *     carries; reshaping to match it would invent a normalisation that never
  *     happened.
- *  2. Stripping needs the COMPLETE key inventory of `searchResultItemSchema`,
- *     whose closure reaches `candidateVerdictSchema` in `@materialgraph/contracts`
- *     — a recursive hand-mirror that would have to stay in step forever, and a
- *     wider surface than the validation it would serve.
+ *  2. Stripping needs the COMPLETE key inventory of `searchResultItemSchema`
+ *     — a hand-mirror that would have to stay in step forever, and a wider
+ *     surface than the validation it would serve.
  *  3. An additive server field then reaches consumers without an SDK release,
  *     which matters while new EVENT types still require one (MG-658).
  * The ONE exception is `.default([])`: an omitted `results` / `inferredCategories`
@@ -50,12 +49,10 @@
  * optional string, `MatchCategoryInference` items, and every
  * `SearchResultItem` in `results[]` are checked exhaustively. Item validation is
  * the shared `checkSearchResultItem` (`search-result-validation.ts`), which
- * mirrors `searchResultItemSchema` and its whole closure down to
- * `candidateVerdictSchema` — including both of its `.superRefine()` cross-field
- * invariants.
+ * mirrors `searchResultItemSchema` and its whole closure.
  */
 import { MaterialGraphError } from "./errors.js";
-import { MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
+import { MATCH_ERROR_REASONS, MATCH_IMAGE_TYPES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 import { readNdjsonLines } from "./ndjson.js";
 import { findSdkOperation } from "./operations.js";
 import { checkSearchResultItems } from "./search-result-validation.js";
@@ -212,6 +209,13 @@ const readFrame = (value, fail) => {
         }
         case "error": {
             requireString(record.message, "`message`", fail);
+            if (record.reason !== undefined) {
+                requireEnum(record.reason, MATCH_ERROR_REASONS, "`reason`", fail);
+            }
+            if (record.retriable !== undefined &&
+                typeof record.retriable !== "boolean") {
+                throw fail("`retriable` must be a boolean");
+            }
             return record;
         }
         default: {

package/match-types.d.ts

@@ -9,6 +9,7 @@ import type { CorpusScope } from "./corpus-scope-types.js";
  * along its natural seam: everything a caller of `client.match()` needs, and
  * nothing else. The STREAMING contracts live in `match-stream-types.ts`.
  */
+import type { MatchWorkflowResult } from "./match-stream-types.js";
 import type { SearchFilter } from "./search-refinement-types.js";
 import type { OpenEnum, PaletteSwatch, SearchResultItem } from "./types.js";
 /** An inferred product-type category from the query image, with its boost. */
@@ -74,6 +75,29 @@ export type MatchResponse = {
     segmentPalette?: PaletteSwatch[] | null;
     note?: string;
 };
+/**
+ * What a BUFFERED `match()` actually answers with, either shape.
+ *
+ * An IMAGE input (`imageBase64` or `imageUrl`) runs the same workflow the
+ * stream lane runs — image kind first, then the swatch shortcut or the scene
+ * route — and answers in {@link MatchWorkflowResult}. A `vector` input has no
+ * bytes to read a kind from and keeps the thin {@link MatchResponse} leaf.
+ * The server declares exactly this as an `anyOf` of the two.
+ *
+ * TELL THEM APART BY A FIELD THAT ONLY ONE HAS, never by what you sent:
+ * `imageType` is required on the workflow shape and absent from the leaf, and
+ * `qualityFloor` is required on the leaf and absent from the workflow shape.
+ *
+ * ```ts
+ * const answer = await client.match({ imageBase64 });
+ * if ("imageType" in answer) {
+ *   for (const surface of answer.surfaces) render(surface);
+ * } else {
+ *   report(answer.qualityFloor, answer.droppedBelowFloor);
+ * }
+ * ```
+ */
+export type MatchAnswer = MatchResponse | MatchWorkflowResult;
 /** The Material Match request body — exactly one of `imageBase64`, `imageUrl`, `vector`. */
 export type MatchInput = {
     imageBase64?: string;