@instruments/materialgraph 3.2.0 → 3.3.0

package/baseline-types.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @module baseline-types
+ * @description Hand-maintained mirror of the Performance Baseline reads' wire
+ * shapes (`list_baselines`, `check_baselines`). The source of truth is
+ * `packages/search/src/baselines/baselines-contract.ts`; this SDK has no
+ * runtime dependency on `@materialgraph/search`, so the shapes are copied
+ * here and `contract-parity.test.ts` keeps them honest.
+ */
+import type { OpenEnum } from "./types.js";
+/** Why a baseline exists. How binding it is on a project, the project decides. */
+export type BaselineStrength = OpenEnum<"code_driven" | "industry_guideline" | "common_practice">;
+/** The published source a baseline was read from. */
+export interface BaselineSource {
+    citation: string;
+    edition: string;
+    publisher: string;
+    /** The day the page at `url` was read (ISO date). */
+    readOn: string;
+    url: string;
+}
+/** One way to meet a baseline: a `listVariants()` `filters` value. */
+export type BaselineWayToMeet = {
+    terms: {
+        field: string;
+        op: "in";
+        values: string[];
+    }[];
+} | {
+    numbers: {
+        field: string;
+        op: "gte";
+        value: number;
+    }[];
+};
+/**
+ * What a kind of material is normally expected to achieve in a kind of
+ * project. A typical expectation with its published source, never a code
+ * determination.
+ */
+export interface Baseline {
+    /** What it asks for, in a specifier's words. */
+    expects: string;
+    id: string;
+    note: string;
+    productTypeIds: string[];
+    sources: BaselineSource[];
+    /** The rooms it is for; null when it holds anywhere in the project. */
+    spaces: string[] | null;
+    strength: BaselineStrength;
+    /** A variant matching any one of these meets the baseline. */
+    waysToMeet: BaselineWayToMeet[];
+}
+/** Options for `listBaselines()` (GET `/api/v1/baselines`). */
+export interface ListBaselinesOptions {
+    /** Keep baselines for these product types; omit for all. */
+    productTypeIds?: readonly string[];
+    /** A `sector` dictionary term that has baselines, e.g. `hospitality`. */
+    sector: string;
+    /** A room from the `use` dictionary, e.g. `corridor`. Omit for anywhere. */
+    space?: string;
+}
+export interface ListBaselinesResult {
+    baselines: Baseline[];
+    /** Show this wherever a baseline is shown. */
+    caveat: string;
+    sector: string;
+    space: string | null;
+    /** Rooms in this sector that have baselines of their own. */
+    spacesWithBaselines: string[];
+}
+/** Input for `checkBaselines()` (POST `/api/v1/baselines/check`). */
+export interface CheckBaselinesInput {
+    sector: string;
+    space?: string;
+    /** 1 to 50 variant ids. */
+    variantIds: readonly string[];
+}
+/** `not_stated`: the brand states no value on that scale. A gap, never a fail. */
+export type BaselineResult = OpenEnum<"matches" | "does_not_match" | "not_stated">;
+export interface CheckBaselinesResult {
+    /** The baselines applied, each with how many variants fell under each result. */
+    baselines: (Baseline & {
+        counts: {
+            doesNotMatch: number;
+            matches: number;
+            notStated: number;
+        };
+    })[];
+    /** Show this wherever a result is shown. */
+    caveat: string;
+    sector: string;
+    space: string | null;
+    unavailableVariantIds?: string[];
+    unresolvedVariantIds?: string[];
+    variants: {
+        brand: string;
+        name: string;
+        product: string;
+        productType: string | null;
+        /** Empty: no baseline covers this product type here. */
+        results: {
+            baselineId: string;
+            result: BaselineResult;
+            /** What the brand states for the attributes the baseline reads. */
+            stated: {
+                attributeId: string;
+                value: string;
+            }[];
+        }[];
+        variantId: string;
+    }[];
+}

package/baseline-types.js

@@ -0,0 +1 @@
+export {};

package/client-response-schema.js

@@ -14,7 +14,7 @@ const openStrings = new Set([
     "MaterialTile.imageSource",
     "PairingItem.availability",
     "PairingItem.imageSource",
-    "PairingItem.demand.momentum.state",
+    "PairingItem.demand.trend",
     "PairingItem.ranking.basis",
     "PairingOrdering.anchorColorBasis",
     "PairingOrdering.applied",

package/client-vocabulary.d.ts

@@ -1,6 +1,8 @@
+import type { ListBaselinesOptions, ListBaselinesResult } from "./baseline-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { ListEnumValuesOptions, ListEnumValuesResult } from "./list-enum-values-types.js";
 import type { ListAttributesOptions, ListAttributesResult, ResolveColorOptions, ResolveColorResponse } from "./types.js";
 export declare const resolveColor: (transport: HttpTransport, name: string, signal?: AbortSignal, options?: ResolveColorOptions) => Promise<ResolveColorResponse>;
 export declare const listAttributes: (transport: HttpTransport, options?: ListAttributesOptions, signal?: AbortSignal) => Promise<ListAttributesResult>;
 export declare const listEnumValues: (transport: HttpTransport, options?: ListEnumValuesOptions, signal?: AbortSignal) => Promise<ListEnumValuesResult>;
+export declare const listBaselines: (transport: HttpTransport, options: ListBaselinesOptions, signal?: AbortSignal) => Promise<ListBaselinesResult>;

package/client-vocabulary.js

@@ -28,3 +28,11 @@ export const listEnumValues = async (transport, options, signal) => await transp
     },
     signal,
 });
+export const listBaselines = async (transport, options, signal) => await transport.requestJson(resolveOperation("list_baselines"), {
+    query: {
+        productTypeIds: commaList(options.productTypeIds),
+        sector: options.sector,
+        space: options.space,
+    },
+    signal,
+});

package/client.d.ts

@@ -1,4 +1,5 @@
 import type { ApplicabilityOptions, AssociatedOptions } from "./association-types.js";
+import type { CheckBaselinesInput, CheckBaselinesResult, ListBaselinesOptions, ListBaselinesResult } from "./baseline-types.js";
 import type { BrandsOptions } from "./brand-types.js";
 import { CategoriesClient } from "./categories-client.js";
 import type { MaterialGraphClientOptions } from "./client-config.js";
@@ -8,6 +9,7 @@ import type { RateLimit } from "./errors.js";
 import type { FindSampledTogetherInput, FindSampledTogetherOutput } from "./find-sampled-together-types.js";
 import type { FindVariantsByColorInput, FindVariantsByColorOutput } from "./find-variants-by-color-types.js";
 import type { FindVariantsByVectorInput, FindVariantsByVectorOutput } from "./find-variants-by-vector-types.js";
+import type { GetVariantDemandInput, GetVariantDemandOutput, ListRisingVariantsInput, ListRisingVariantsOutput } from "./get-variant-demand-types.js";
 import type { GetVariantOptions, GetVariantOutput } from "./get-variant-types.js";
 import type { VariantId } from "./identifiers.js";
 import type { ListEnumValuesOptions, ListEnumValuesResult } from "./list-enum-values-types.js";
@@ -113,6 +115,19 @@ export declare class MaterialGraphClient {
      * never a guess. The submitted URL is never persisted.
      */
     resolveVariant(input: ResolveVariantInput, signal?: AbortSignal): Promise<ResolveVariantOutput>;
+    /**
+     * How much each of 1 to 48 variants is sampled by Material Bank members
+     * (POST `/api/v1/demand`): `samplePercentile` within its category, with a
+     * `trend` and the `change` of this year against the year before. Results
+     * keep request order. No count is returned.
+     */
+    getVariantDemand(input: GetVariantDemandInput, signal?: AbortSignal): Promise<GetVariantDemandOutput>;
+    /**
+     * The variants of one category sampled at least 15% more this year than
+     * the year before (GET `/api/v1/demand/rising`), largest `change` first.
+     * No count is returned.
+     */
+    listRisingVariants(input: ListRisingVariantsInput, signal?: AbortSignal): Promise<ListRisingVariantsOutput>;
     /**
      * THE QUESTION: "tell me about THIS variant" (GET
      * `/api/v1/variants/{variantId}`, `get_variant`).
@@ -229,9 +244,9 @@ export declare class MaterialGraphClient {
     /**
      * Every Sampled Together pair in the current generation (GET
      * `/api/v1/variants/sampled-together/pairs`), trailing 36 months, sampled,
-     * each pair once with `a < b`. `aProjects` and `bProjects` are each side's
-     * own project total, so a sample pack can be dropped without one call per
-     * variant. Follow `nextCursor` until it is null; a page is not a total.
+     * each pair once with `a < b`. `packShare` is the pair's share of the rarer
+     * side's own sampled projects, so a sample pack can be dropped without one
+     * call per variant. Follow `nextCursor` until it is null; a page is not a total.
      */
     listSampledTogetherPairs(input?: ListSampledTogetherPairsInput, signal?: AbortSignal): Promise<ListSampledTogetherPairsOutput>;
     /**
@@ -269,6 +284,20 @@ export declare class MaterialGraphClient {
      * `pageInfo.endCursor` for the next page.
      */
     listEnumValues(options?: ListEnumValuesOptions, signal?: AbortSignal): Promise<ListEnumValuesResult>;
+    /**
+     * The Performance Baselines for a sector, and for a room within it when one
+     * is named: what a kind of material is normally expected to achieve, each
+     * with why it exists and its published source. Each `waysToMeet` entry is a
+     * `filters` value for {@link MaterialGraphClient.listVariants}. A typical
+     * expectation, never a code determination: show `caveat` with it.
+     */
+    listBaselines(options: ListBaselinesOptions, signal?: AbortSignal): Promise<ListBaselinesResult>;
+    /**
+     * Up to 50 variants read against a sector's Performance Baselines. Each
+     * result is `matches`, `does_not_match` or `not_stated`, with what the brand
+     * states; `not_stated` is a gap in the data and never a failure.
+     */
+    checkBaselines(input: CheckBaselinesInput, signal?: AbortSignal): Promise<CheckBaselinesResult>;
     /**
      * THE QUESTION: "what is this key allowed to do?" Check `scopes` before
      * offering a capability: the write surfaces need `mg:ingest` / `mg:compose`,

package/client.js

@@ -2,7 +2,7 @@ import { applicability, declaredFinishes, declaredProducts, } from "./associatio
 import { listBrands } from "./brands-client.js";
 import { CategoriesClient } from "./categories-client.js";
 import { DEFAULT_BASE_URL } from "./client-config.js";
-import { listAttributes as listAttributesCall, listEnumValues as listEnumValuesCall, resolveColor as resolveColorCall, } from "./client-vocabulary.js";
+import { listAttributes as listAttributesCall, listBaselines as listBaselinesCall, listEnumValues as listEnumValuesCall, resolveColor as resolveColorCall, } from "./client-vocabulary.js";
 import { ColorsClient } from "./colors-client.js";
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
@@ -153,6 +153,30 @@ export class MaterialGraphClient {
             signal,
         });
     }
+    /**
+     * How much each of 1 to 48 variants is sampled by Material Bank members
+     * (POST `/api/v1/demand`): `samplePercentile` within its category, with a
+     * `trend` and the `change` of this year against the year before. Results
+     * keep request order. No count is returned.
+     */
+    async getVariantDemand(input, signal) {
+        return await this.#transport.requestJson(operation("get_variant_demand"), {
+            body: input,
+            signal,
+        });
+    }
+    /**
+     * The variants of one category sampled at least 15% more this year than
+     * the year before (GET `/api/v1/demand/rising`), largest `change` first.
+     * No count is returned.
+     */
+    async listRisingVariants(input, signal) {
+        return await this.#get("list_rising_variants", {
+            category: input.category,
+            limit: input.limit === undefined ? undefined : String(input.limit),
+            projectType: input.projectType,
+        }, signal);
+    }
     // ── Materials ──────────────────────────────────────────────────────────────
     /**
      * THE QUESTION: "tell me about THIS variant" (GET
@@ -355,9 +379,9 @@ export class MaterialGraphClient {
     /**
      * Every Sampled Together pair in the current generation (GET
      * `/api/v1/variants/sampled-together/pairs`), trailing 36 months, sampled,
-     * each pair once with `a < b`. `aProjects` and `bProjects` are each side's
-     * own project total, so a sample pack can be dropped without one call per
-     * variant. Follow `nextCursor` until it is null; a page is not a total.
+     * each pair once with `a < b`. `packShare` is the pair's share of the rarer
+     * side's own sampled projects, so a sample pack can be dropped without one
+     * call per variant. Follow `nextCursor` until it is null; a page is not a total.
      */
     async listSampledTogetherPairs(input = {}, signal) {
         return await this.#get("list_sampled_together_pairs", {
@@ -412,6 +436,24 @@ export class MaterialGraphClient {
     async listEnumValues(options, signal) {
         return await listEnumValuesCall(this.#transport, options, signal);
     }
+    /**
+     * The Performance Baselines for a sector, and for a room within it when one
+     * is named: what a kind of material is normally expected to achieve, each
+     * with why it exists and its published source. Each `waysToMeet` entry is a
+     * `filters` value for {@link MaterialGraphClient.listVariants}. A typical
+     * expectation, never a code determination: show `caveat` with it.
+     */
+    async listBaselines(options, signal) {
+        return await listBaselinesCall(this.#transport, options, signal);
+    }
+    /**
+     * Up to 50 variants read against a sector's Performance Baselines. Each
+     * result is `matches`, `does_not_match` or `not_stated`, with what the brand
+     * states; `not_stated` is a gap in the data and never a failure.
+     */
+    async checkBaselines(input, signal) {
+        return await this.#post("check_baselines", input, signal);
+    }
     // Hard-specification search (formerly `bySpec()`) moved to
     // {@link MaterialGraphClient.listVariants}
     // (MG-2222): each `attribute:value` criterion is one `filters` condition —

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

@@ -37,6 +37,7 @@ export interface FindVariantsByColorInput {
     cursor?: string;
     /** Palette only: targets from this image's colors, not `colors[]`. */
     image?: ImageReferenceInput;
+    /** Variants a page, 1 to 24 (a larger value is a 400). Omitted: 16 for contains and palette, every given id for rerank. */
     limit?: number;
     mode: FindVariantsByColorMode;
     /** Independent specification type or group keys, e.g. wallcovering or coatings; filters specification types, not source categories. */

package/get-variant-demand-types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @module get-variant-demand-types
+ * @description Hand-maintained mirror of `get_variant_demand`'s and
+ * `list_rising_variants`' wire shapes.
+ * The source of truth is `packages/demand/src/contract.ts`; this SDK has
+ * no runtime dependency on `@materialgraph/demand`, so the shapes are copied
+ * here.
+ */
+import type { OpenEnum } from "./types.js";
+export interface GetVariantDemandInput {
+    /** 1 to 48 variant ids. */
+    variantIds: string[];
+    /** One Material Bank project type; omit for every project type together. */
+    projectType?: string;
+}
+export type DemandTrend = OpenEnum<"rising" | "steady" | "falling">;
+export type VariantDemand = {
+    state: "measured";
+    variantId: string;
+    /** The category the percentile is ranked within. */
+    category: string;
+    /** Share of the category's variants sampled as much or less, 1 to 100. */
+    samplePercentile: number;
+    /** Null when the year before cannot be shown. */
+    trend: DemandTrend | null;
+    /** This year against the year before; 0.4 is 40% more. Null with `trend`. */
+    change: number | null;
+}
+/** Too few members sampled it to show, or nobody did. */
+ | {
+    state: "not_shown";
+    variantId: string;
+} | {
+    state: "unknown_variant";
+    variantId: string;
+};
+export interface GetVariantDemandOutput {
+    /** Last day of the measured year, as an ISO date. */
+    asOf: string;
+    basis: "measured";
+    source: string;
+    /** One reading per requested id, in request order, duplicates kept. */
+    results: VariantDemand[];
+}
+export interface ListRisingVariantsInput {
+    /** A MaterialGraph category id, such as `wallcovering`. */
+    category: string;
+    /** Variants to return, at most 100. Default 20. */
+    limit?: number;
+    /** One Material Bank project type; omit for every project type together. */
+    projectType?: string;
+}
+export interface RisingVariant {
+    variantId: string;
+    /** Share of the category's variants sampled as much or less, 1 to 100. */
+    samplePercentile: number;
+    trend: DemandTrend | null;
+    /** This year against the year before; 0.4 is 40% more. */
+    change: number | null;
+}
+export interface ListRisingVariantsOutput {
+    /** Last day of the measured year, as an ISO date. */
+    asOf: string;
+    basis: "measured";
+    category: string;
+    /** Largest change first. */
+    results: RisingVariant[];
+    source: string;
+}

package/get-variant-demand-types.js

@@ -0,0 +1 @@
+export {};

package/get-variant-types.d.ts

@@ -59,7 +59,7 @@ export interface GetVariantOutput {
     }[];
     attributes: Record<string, {
         value: unknown;
-        valueSource: "brand" | "material_bank" | "measured" | "manual" | null;
+        valueSource: "brand" | "material_bank" | "measured" | "manual" | "inferred" | null;
         wording: string | null;
         level: "variant" | "product" | "brand";
     }>;

package/index.d.ts

@@ -4,10 +4,12 @@ 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, 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 { Baseline, BaselineResult, BaselineSource, BaselineStrength, BaselineWayToMeet, CheckBaselinesInput, CheckBaselinesResult, ListBaselinesOptions, ListBaselinesResult, } from "./baseline-types.js";
 export type { ListEnumValuesOptions, EnumValueMatch, EnumValueItem, ListEnumValuesResult, } from "./list-enum-values-types.js";
 export type { GetVariantIfc, GetVariantOptions, GetVariantOutput, } from "./get-variant-types.js";
 export type { ImageReferenceInput } from "./image-reference-types.js";
 export type { SampledTogetherProjectType, FindSampledTogetherInput, FindSampledTogetherRow, FindSampledTogetherOutput, } from "./find-sampled-together-types.js";
+export type { GetVariantDemandInput, GetVariantDemandOutput, DemandTrend, VariantDemand, ListRisingVariantsInput, ListRisingVariantsOutput, RisingVariant, } from "./get-variant-demand-types.js";
 export type { ListSampledTogetherPairsInput, ListSampledTogetherPairsOutput, SampledTogetherPair, } from "./list-sampled-together-pairs-types.js";
 export type { FindVariantsByColorMode, ColorConditionInput, FindVariantsByColorInput, ColorConditionReceipt, PaintCatalogVariant, ResolvedColor, ColorAlternative, UnresolvedColor, ColorVariantMatch, ColorPageInfo, FindVariantsByColorContainsResult, FindVariantsByColorPaletteResult, ColorRankedSeed, ColorRankMatch, ResolvedColorReference, CompareColorSimilarityReference, FindVariantsByColorRerankResult, FindVariantsByColorOutput, } from "./find-variants-by-color-types.js";
 export { FIND_VARIANTS_BY_VECTOR_MODES } from "./find-variants-by-vector-types.js";
@@ -18,7 +20,7 @@ export type { OpaqueId, VariantId, ProductId, BatchId, SourceFileId, ProjectId,
 export type { FileInput, UploadSourceMaterialInput, SourceMaterialReceiptFile, SourceMaterialBatchReceipt, } from "./source-material-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 { OpenEnum, JsonValue, OklabTriple, MaterialColor, ImageSource, MaterialAvailability, MaterialTile, DemandMomentum, CompanionDemand, ProjectTypeShare, CospecPairing, ColorPairing, PairingOrderMode, PairingRanking, PairingOrdering, PairingItem, PairingsResponse, AttributeMatch, AttributeListItem, OutsideScopeAttribute, ListAttributesResult, WhoamiResponse, PairingsOptions, ListAttributesOptions, ExtractedPalette, ExtractPaletteResponse, ExtractPaletteInput, ResolveValueCandidate, ValueResolution, ResolveColorOptions, ResolveColorCatalogVariant, ResolveColorVariant, ResolveColorResponse, BySpecVerdictState, BySpecVerdictCell, BySpecVerdict, MaterialVerdict, BySpecUnresolvedCriterion, } from "./types.js";
+export type { OpenEnum, JsonValue, OklabTriple, MaterialColor, ImageSource, MaterialAvailability, MaterialTile, CompanionDemand, ProjectTypeShare, CospecPairing, ColorPairing, PairingOrderMode, PairingRanking, PairingOrdering, PairingItem, PairingsResponse, AttributeMatch, AttributeListItem, OutsideScopeAttribute, ListAttributesResult, WhoamiResponse, PairingsOptions, ListAttributesOptions, ExtractedPalette, ExtractPaletteResponse, ExtractPaletteInput, ResolveValueCandidate, ValueResolution, ResolveColorOptions, ResolveColorCatalogVariant, ResolveColorVariant, ResolveColorResponse, BySpecVerdictState, BySpecVerdictCell, BySpecVerdict, MaterialVerdict, BySpecUnresolvedCriterion, } from "./types.js";
 export type { ResolveVariantInput, ResolveVariantSubject, ResolveVariantEvidence, ResolveVariantReceipt, ResolveVariantUnresolvedReason, ResolveVariantOutput, } from "./resolve-variant-types.js";
 export { CategoriesClient } from "./categories-client.js";
 export type { CategoryRef, CategoryKind, CategoryMatch, CategoryItem, CategoriesPageInfo, CategoriesListInput, CategoriesListResult, CategoryConcept, CategoryProductCategory, CategoriesGetResult, } from "./category-types.js";

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

@@ -22,9 +22,11 @@ export interface SampledTogetherPair {
     /** Above 1 is sampled together more often than chance. */
     lift: number;
     lastSampledTogetherAt: string | null;
-    /** Each side's own sampled project total; null when unknown. */
-    aProjects: number | null;
-    bProjects: number | null;
+    /**
+     * The pair's projects as a share of the rarer side's own sampled projects,
+     * 0 to 1. Near 1 is a sample pack. Null when either side has no total.
+     */
+    packShare: number | null;
 }
 export interface ListSampledTogetherPairsOutput {
     window: "trailing_36mo";
@@ -32,8 +34,6 @@ export interface ListSampledTogetherPairsOutput {
     windowStart: string | null;
     /** How fresh the pair evidence is. */
     windowEnd: string | null;
-    /** End of the window the per-side totals were counted over. */
-    projectTotalsWindowEnd: string | null;
     pairs: SampledTogetherPair[];
     nextCursor: string | null;
 }

package/list-variants-types.d.ts

@@ -137,7 +137,7 @@ export interface ListVariantsInput {
     /** Every condition, across `terms`/`numbers`/`presence`/`anyField`, must match. */
     filters?: FilterGroups;
     include?: ListVariantsInclude[];
-    /** 1–50; defaults to 10. */
+    /** 1–50; defaults to 10. The most a page holds: a page also stops at 64 KB, so wide rows (`include`, many `attributes`) can end it early with `hasNextPage` true. Follow `endCursor` until it is false, even for a `variant in` list of 50 ids or fewer. */
     limit?: number;
     /**
      * Find by name (MG-2222): every word must start a word of the product or
@@ -163,7 +163,7 @@ export interface ListVariantsInput {
  */
 export interface ListVariantsPreference {
     looks?: {
-        by: ("named" | "stated" | "described")[];
+        by: ("named" | "stated" | "described" | "related")[];
         index: number;
         words?: string;
     }[];
@@ -272,6 +272,7 @@ export interface ListVariantsOutput {
         matched: boolean;
         word: string;
     }[];
+    /** `hasNextPage` true means more rows remain, including a requested `variant in` id not on this page; it is never in the id lists below until its page is read. */
     pageInfo: {
         endCursor: string | null;
         hasNextPage: boolean;

package/material-block-types.d.ts

@@ -56,7 +56,7 @@ export interface MaterialBlockProjectionField {
     attributeId: string;
     label: string;
     value: MaterialBlockFieldValue;
-    /** The value dictionary's label for a single-term `value`. Absent when no label is on record; `value` stays the canonical token. */
+    /** The value in words, as the product page shows it: a term by its label, a measurement with its unit, a composition by its ingredients and shares. Absent when the field holds nothing; `value` stays the canonical form. */
     displayValue?: string;
     unit?: string;
     status: MaterialBlockFieldStatus;

package/operation-responses.d.ts

@@ -1,5 +1,6 @@
 /** Response types belong to operation ids, never a caller-selected generic. */
 import type { ApplicabilityResponse, DeclaredAssociationsResponse } from "./association-types.js";
+import type { CheckBaselinesResult, ListBaselinesResult } from "./baseline-types.js";
 import type { ListBrandsPage } from "./brand-types.js";
 import type { CategoriesGetResult, CategoriesListResult } from "./category-types.js";
 import type { CategoryColorProfilesResponse } from "./color-profiles-types.js";
@@ -7,6 +8,7 @@ import type { DiscoveryReference, DiscoveryTerms, ColorlessVariantsResult, Varia
 import type { FindSampledTogetherOutput } from "./find-sampled-together-types.js";
 import type { FindVariantsByColorOutput } from "./find-variants-by-color-types.js";
 import type { FindVariantsByVectorOutput } from "./find-variants-by-vector-types.js";
+import type { GetVariantDemandOutput, ListRisingVariantsOutput } from "./get-variant-demand-types.js";
 import type { GetVariantOutput } from "./get-variant-types.js";
 import type { ListEnumValuesResult } from "./list-enum-values-types.js";
 import type { ListSampledTogetherPairsOutput } from "./list-sampled-together-pairs-types.js";
@@ -21,6 +23,8 @@ import type { SearchVariantsOutput } from "./search-variants-types.js";
 import type { SourceMaterialBatchReceipt } from "./source-material-types.js";
 import type { ExtractPaletteResponse, ListAttributesResult, PairingsResponse, ResolveColorResponse, WhoamiResponse } from "./types.js";
 export interface OperationResponses {
+    check_baselines: CheckBaselinesResult;
+    list_baselines: ListBaselinesResult;
     get_discovery_reference: DiscoveryReference;
     interpret_discovery_terms: DiscoveryTerms;
     find_colorless_variants: ColorlessVariantsResult;
@@ -33,6 +37,8 @@ export interface OperationResponses {
     catalog_list_enum_values: ListEnumValuesResult;
     extract_image_palette: ExtractPaletteResponse;
     find_sampled_together: FindSampledTogetherOutput;
+    get_variant_demand: GetVariantDemandOutput;
+    list_rising_variants: ListRisingVariantsOutput;
     list_sampled_together_pairs: ListSampledTogetherPairsOutput;
     find_variants_by_color: FindVariantsByColorOutput;
     find_variants_by_vector: FindVariantsByVectorOutput;

package/operations.generated.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.8.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["discoveryReference", "GET", "/api/v1/catalog/discovery-reference", "get_discovery_reference"], readonly ["interpretDiscoveryTerms", "POST", "/api/v1/catalog/interpret-terms", "interpret_discovery_terms"], readonly ["colorlessVariants", "POST", "/api/v1/variants/colorless", "find_colorless_variants"], readonly ["variantSiblings", "GET", "/api/v1/variants/{variantId}/siblings", "list_variant_siblings"], readonly ["colors.nearestPaints", "GET", "/api/v1/colors/nearest-paints", "find_nearest_paints"], readonly ["getCatalogGeneration", "GET", "/api/v1/catalog/generation", "get_catalog_generation"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColor", "GET", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findSampledTogether", "GET", "/api/v1/variants/sampled-together", "find_sampled_together"], readonly ["listSampledTogetherPairs", "GET", "/api/v1/variants/sampled-together/pairs", "list_sampled_together_pairs"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColor", "GET", "/api/v1/search/colors/resolve", "resolve_color_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colors.profiles", "GET", "/api/v1/colors/profiles", "get_category_color_profiles"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["discoveryReference", "GET", "/api/v1/catalog/discovery-reference", "get_discovery_reference"], readonly ["interpretDiscoveryTerms", "POST", "/api/v1/catalog/interpret-terms", "interpret_discovery_terms"], readonly ["colorlessVariants", "POST", "/api/v1/variants/colorless", "find_colorless_variants"], readonly ["variantSiblings", "GET", "/api/v1/variants/{variantId}/siblings", "list_variant_siblings"], readonly ["colors.nearestPaints", "GET", "/api/v1/colors/nearest-paints", "find_nearest_paints"], readonly ["getCatalogGeneration", "GET", "/api/v1/catalog/generation", "get_catalog_generation"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColor", "GET", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findSampledTogether", "GET", "/api/v1/variants/sampled-together", "find_sampled_together"], readonly ["listSampledTogetherPairs", "GET", "/api/v1/variants/sampled-together/pairs", "list_sampled_together_pairs"], readonly ["getVariantDemand", "POST", "/api/v1/demand", "get_variant_demand"], readonly ["listRisingVariants", "GET", "/api/v1/demand/rising", "list_rising_variants"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColor", "GET", "/api/v1/search/colors/resolve", "resolve_color_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["listBaselines", "GET", "/api/v1/baselines", "list_baselines"], readonly ["checkBaselines", "POST", "/api/v1/baselines/check", "check_baselines"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colors.profiles", "GET", "/api/v1/colors/profiles", "get_category_color_profiles"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation<K extends SdkOperationId = SdkOperationId> = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.generated.js

@@ -112,6 +112,13 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/variants/sampled-together/pairs",
         "list_sampled_together_pairs",
     ],
+    ["getVariantDemand", "POST", "/api/v1/demand", "get_variant_demand"],
+    [
+        "listRisingVariants",
+        "GET",
+        "/api/v1/demand/rising",
+        "list_rising_variants",
+    ],
     ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"],
     ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"],
     [
@@ -132,6 +139,8 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/catalog/enum-values",
         "catalog_list_enum_values",
     ],
+    ["listBaselines", "GET", "/api/v1/baselines", "list_baselines"],
+    ["checkBaselines", "POST", "/api/v1/baselines/check", "check_baselines"],
     ["categories.list", "GET", "/api/v1/categories", "list_categories"],
     ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"],
     ["whoami", "GET", "/api/v1/whoami", "whoami"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "type": "module",
   "exports": {
     ".": {

package/response-schemas.generated.d.ts

@@ -1,5 +1,5 @@
 /** The API contract version the schemas were generated from. */
 export declare const RESPONSE_SCHEMA_API_VERSION = "0.8.0";
 /** Every SDK operation whose success response has a published JSON Schema. */
-export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["get_discovery_reference", "interpret_discovery_terms", "find_colorless_variants", "list_variant_siblings", "find_nearest_paints", "get_catalog_generation", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_sampled_together", "list_sampled_together_pairs", "resolve_variant", "get_variant", "resolve_color_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "get_category_color_profiles", "extract_image_palette", "list_brands", "upload_source_material"];
+export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["get_discovery_reference", "interpret_discovery_terms", "find_colorless_variants", "list_variant_siblings", "find_nearest_paints", "get_catalog_generation", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_sampled_together", "list_sampled_together_pairs", "get_variant_demand", "list_rising_variants", "resolve_variant", "get_variant", "resolve_color_name", "catalog_list_attributes", "catalog_list_enum_values", "list_baselines", "check_baselines", "list_categories", "get_category", "whoami", "get_category_color_profiles", "extract_image_palette", "list_brands", "upload_source_material"];
 export declare const RESPONSE_SCHEMA_CATALOG_JSON: string;