@instruments/materialgraph 3.1.0 → 3.3.0

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";
@@ -86,9 +86,7 @@ export class MaterialGraphClient {
             apiKey: options.apiKey,
             baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
             fetch: options.fetch ?? globalThis.fetch,
-            ...(options.timeoutMs === undefined
-                ? {}
-                : { timeoutMs: options.timeoutMs }),
+            timeoutMs: options.timeoutMs,
         });
         this.#transport = transport;
         this.baseUrl = transport.baseUrl;
@@ -155,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
@@ -181,10 +203,10 @@ export class MaterialGraphClient {
             blocks: options?.blocks !== undefined && options.blocks.length > 0
                 ? options.blocks.join(",")
                 : undefined,
+            ifc: options?.ifc === true ? "true" : undefined,
             observations: options?.observations !== undefined && options.observations.length > 0
                 ? options.observations.join(",")
                 : undefined,
-            ifc: options?.ifc === true ? "true" : undefined,
         }, signal, { variantId });
     }
     async materialBlocks(variantId, signal) {
@@ -264,7 +286,6 @@ export class MaterialGraphClient {
             colors: input.colors !== undefined && input.colors.length > 0
                 ? JSON.stringify(input.colors)
                 : undefined,
-            searchCatalogSubset: input.searchCatalogSubset,
             cursor: input.cursor,
             filters: input.filters ? JSON.stringify(input.filters) : undefined,
             include: input.include !== undefined && input.include.length > 0
@@ -281,6 +302,7 @@ export class MaterialGraphClient {
             orderBy: input.orderBy !== undefined && input.orderBy.length > 0
                 ? JSON.stringify(input.orderBy)
                 : undefined,
+            searchCatalogSubset: input.searchCatalogSubset,
             words: input.words !== undefined && input.words.length > 0
                 ? input.words.join(",")
                 : undefined,
@@ -357,17 +379,17 @@ 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", {
-            ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
-            ...(input.limit === undefined ? {} : { limit: String(input.limit) }),
-            ...(input.minProjects === undefined
-                ? {}
-                : { minProjects: String(input.minProjects) }),
+            cursor: input.cursor,
+            limit: input.limit === undefined ? undefined : String(input.limit),
+            minProjects: input.minProjects === undefined
+                ? undefined
+                : String(input.minProjects),
         }, signal);
     }
     /**
@@ -414,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/color-profiles-types.d.ts

@@ -14,7 +14,7 @@ import type { OpenEnum } from "./types.js";
  */
 export type CategoryTier = OpenEnum<"group" | "type" | "merged">;
 /** One representative color bucket of a category. */
-export type CategoryColor = {
+export interface CategoryColor {
     hex: string;
     oklab: {
         l: number;
@@ -24,8 +24,8 @@ export type CategoryColor = {
     variantCount: number;
     /** This bucket's share of the selection's colored variants, 0 to 1. */
     proportion: number;
-};
-export type CategoryColorProfile = {
+}
+export interface CategoryColorProfile {
     categoryKey: string;
     level: CategoryTier;
     name: string;
@@ -39,12 +39,12 @@ export type CategoryColorProfile = {
     avgLightness: number;
     avgChroma: number;
     colors: CategoryColor[];
-};
-export type CategoryColorProfilesResponse = {
+}
+export interface CategoryColorProfilesResponse {
     profiles: CategoryColorProfile[];
-};
+}
 /** Request parameters for `colors.profiles()`. */
-export type ColorProfilesParams = {
+export interface ColorProfilesParams {
     /** 1 to 8 category keys, at the tier named by `groupBy`. */
     productTypeIds: readonly string[];
     /**
@@ -57,4 +57,4 @@ export type ColorProfilesParams = {
     topN?: number;
     /** `"diverse"` maximizes visual distinctness instead of frequency. */
     select?: "frequency" | "diverse";
-};
+}

package/color-wire-types.d.ts

@@ -5,28 +5,28 @@
  */
 import type { OpenEnum } from "./types.js";
 /** A color in OKLab: lightness 0 to 1, and the green-red and blue-yellow axes. */
-export type OKLab = {
+export interface OKLab {
     L: number;
     a: number;
     b: number;
-};
+}
 /** A region of color: chroma, hue (null for neutrals) and lightness bounds. */
-export type ColorRegion = {
+export interface ColorRegion {
     chroma: [number, number];
     hue: [number, number] | null;
     lightness: [number, number];
-};
+}
 /** One of ColorScope's fifteen color families. */
 export type ColorFamilyId = OpenEnum<"beige" | "black" | "blue" | "brown" | "cream" | "gray" | "green" | "orange" | "pink" | "purple" | "red" | "taupe" | "teal" | "white" | "yellow">;
 /** A named color a resolution lands on, and how close the input is to it. */
-export type ColorResolutionMatch = {
+export interface ColorResolutionMatch {
     band: OpenEnum<"inside" | "near" | "far">;
     family: ColorFamilyId;
     hex: string;
     id: string;
     name: string;
     range: ColorRegion;
-};
+}
 /** What ColorScope makes of a color name: resolved to a color, or why not. */
 export type ColorResolution = {
     kind: "resolved";

package/colors-client.d.ts

@@ -29,9 +29,9 @@ import type { JsonOperationId, OperationResponses } from "./operation-responses.
  * likeness, never a stated color specification.
  */
 /** The client's own request primitives, handed down so this file owns no transport. */
-export type ColorsTransport = {
-    get<K extends JsonOperationId>(operationId: K, query?: QueryParams, signal?: AbortSignal): Promise<OperationResponses[K]>;
-};
+export interface ColorsTransport {
+    get: <K extends JsonOperationId>(operationId: K, query?: QueryParams, signal?: AbortSignal) => Promise<OperationResponses[K]>;
+}
 export declare class ColorsClient {
     #private;
     constructor(transport: ColorsTransport);

package/discovery-context-types.d.ts

@@ -1,6 +1,6 @@
 import type { MaterialTile } from "./material-types.js";
 /** Static registry definitions and MG-owned discovery policy, without product counts. */
-export type DiscoveryReference = {
+export interface DiscoveryReference {
     attributes: {
         id: string;
         name: string;
@@ -23,21 +23,21 @@ export type DiscoveryReference = {
         description: string;
     }[];
     admittedBrandIds: string[];
-};
-export type InterpretDiscoveryTermsInput = {
+}
+export interface InterpretDiscoveryTermsInput {
     text: string;
     categoryIds: readonly string[];
-};
-export type DiscoveryTerms = {
+}
+export interface DiscoveryTerms {
     categories: {
         categoryIds: string[];
         words: string[];
     } | null;
     colorWordHexes: string[];
-};
-export type ColorlessVariantsResult = {
+}
+export interface ColorlessVariantsResult {
     variantIds: string[];
-};
+}
 /** A sibling uses the same tile contract as the catalog's material cards. */
 export type VariantSibling = MaterialTile & {
     distinction?: string;

package/errors.d.ts

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

package/errors.js

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

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

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