@instruments/materialgraph 0.25.0 → 0.27.0

package/http-transport.js

@@ -8,13 +8,14 @@
  */
 import { MaterialGraphError } from "./errors.js";
 import { operationPath } from "./operations.js";
-function parseIntOrNull(value) {
-    if (value === null)
+const parseIntOrNull = (value) => {
+    if (value === null) {
         return null;
+    }
     const parsed = Number.parseInt(value, 10);
     return Number.isNaN(parsed) ? null : parsed;
-}
-function parseRateLimit(headers) {
+};
+const parseRateLimit = (headers) => {
     const limit = parseIntOrNull(headers.get("x-ratelimit-limit"));
     const remaining = parseIntOrNull(headers.get("x-ratelimit-remaining"));
     const reset = parseIntOrNull(headers.get("x-ratelimit-reset"));
@@ -26,7 +27,7 @@ function parseRateLimit(headers) {
         return null;
     }
     return { limit, remaining, reset, retryAfter };
-}
+};
 export class HttpTransport {
     baseUrl;
     apiKey;
@@ -34,7 +35,7 @@ export class HttpTransport {
     #lastRateLimit = null;
     constructor(options) {
         this.apiKey = options.apiKey;
-        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.baseUrl = options.baseUrl.replace(/\/+$/u, "");
         this.fetch = options.fetch;
     }
     get lastRateLimit() {
@@ -43,8 +44,8 @@ export class HttpTransport {
     /** The bearer + JSON `Accept` headers, plus any per-request additions. */
     authHeaders(extra) {
         return {
-            Authorization: `Bearer ${this.apiKey}`,
             Accept: "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
             ...extra,
         };
     }
@@ -52,12 +53,14 @@ export class HttpTransport {
         const url = new URL(`${this.baseUrl}${path}`);
         if (query) {
             for (const [key, value] of Object.entries(query)) {
-                if (value === undefined || value === null)
+                if (value === undefined || value === null) {
                     continue;
+                }
                 if (Array.isArray(value)) {
                     for (const item of value) {
-                        if (item !== undefined && item !== null)
+                        if (item !== undefined && item !== null) {
                             url.searchParams.append(key, String(item));
+                        }
                     }
                 }
                 else {
@@ -83,17 +86,17 @@ export class HttpTransport {
         let response;
         try {
             response = await this.fetch(input.url, {
-                method: input.method,
-                headers: input.headers,
                 body: input.body,
+                headers: input.headers,
+                method: input.method,
                 signal: input.signal,
             });
         }
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                cause,
                 callerSignal: input.signal,
+                cause,
             });
         }
         const rateLimit = parseRateLimit(response.headers);
@@ -105,8 +108,8 @@ export class HttpTransport {
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                cause,
                 callerSignal: input.signal,
+                cause,
             });
         }
         let parsed;
@@ -121,15 +124,15 @@ export class HttpTransport {
         if (!response.ok) {
             throw MaterialGraphError.fromResponse({
                 ...metadata,
-                status: response.status,
-                body: parsed,
-                responseText: text,
-                rateLimit,
                 apiKey: this.apiKey,
+                body: parsed,
                 queryValues: [...requestUrl.searchParams.values()],
+                rateLimit,
+                responseText: text,
+                status: response.status,
             });
         }
-        return { response, text, parsed };
+        return { parsed, response, text };
     }
     /**
      * Open a streaming operation and hand back its UNREAD byte body — the one
@@ -152,20 +155,20 @@ export class HttpTransport {
         let response;
         try {
             response = await this.fetch(url, {
-                method: sdkOperation.method,
+                body: hasBody ? JSON.stringify(options.body) : undefined,
                 headers: this.authHeaders({
                     Accept: options.accept,
                     ...(hasBody ? { "Content-Type": "application/json" } : {}),
                 }),
-                body: hasBody ? JSON.stringify(options.body) : undefined,
+                method: sdkOperation.method,
                 signal: options.signal,
             });
         }
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                cause,
                 callerSignal: options.signal,
+                cause,
             });
         }
         const rateLimit = parseRateLimit(response.headers);
@@ -191,12 +194,12 @@ export class HttpTransport {
             }
             throw MaterialGraphError.fromResponse({
                 ...metadata,
-                status: response.status,
-                body: parsed,
-                responseText: text,
-                rateLimit,
                 apiKey: this.apiKey,
+                body: parsed,
                 queryValues: [...requestUrl.searchParams.values()],
+                rateLimit,
+                responseText: text,
+                status: response.status,
             });
         }
         if (response.body === null) {
@@ -209,16 +212,16 @@ export class HttpTransport {
         const url = this.buildUrl(operationPath(sdkOperation, options.pathParams), options.query);
         const hasBody = options.body !== undefined;
         const { parsed } = await this.send({
-            method: sdkOperation.method,
-            url,
+            body: hasBody ? JSON.stringify(options.body) : undefined,
             headers: this.authHeaders({
                 ...(hasBody ? { "Content-Type": "application/json" } : {}),
                 ...(options.idempotencyKey
                     ? { "Idempotency-Key": options.idempotencyKey }
                     : {}),
             }),
-            body: hasBody ? JSON.stringify(options.body) : undefined,
+            method: sdkOperation.method,
             signal: options.signal,
+            url,
         });
         return parsed;
     }

package/identify-types.d.ts

@@ -1,72 +1,82 @@
 /**
- * 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 interface 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[];
-}
-export interface IdentifySelectedPageSubject {
-    kind: "variant" | "product" | "brand";
+/**
+ * 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[];
+};
+/** 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 interface 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;
-}
-interface IdentifySelectedPageDataBase {
-    receipt: {
-        submittedUrl: string;
-        normalizedUrl: string;
-        normalizationSteps: string[];
-    };
-    evidence: IdentifySelectedPageEvidence[];
-}
-export type IdentifySelectedPageData = (IdentifySelectedPageDataBase & {
+};
+/** 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[];
+};
+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 interface IdentifySelectedPageResult {
-    data: IdentifySelectedPageData;
+export type IdentifyResponse = {
+    data: IdentifyResult;
     meta: {
         operationId: "retrieval.identify";
         requestId: string;
     };
     links: Record<string, never>;
     warnings: [];
-}
+};
 export {};

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,34 +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 "./schedule-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 { PROJECT_EVENT_KINDS } from "./project-types.js";
-export type * from "./project-types.js";
-export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
-export type * from "./run-events.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";
@@ -36,24 +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 "./schedule-reference-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,12 +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 { PROJECT_EVENT_KINDS } from "./project-types.js";
-export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.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,142 @@
+/**
+ * @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 ListVariantsInput = {
+    /** Attribute ids to project under each item's `specifications`. */
+    attributes?: string[];
+    /**
+     * 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 {};