@instruments/materialgraph 3.1.0 → 3.3.0

package/package.json

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

package/parse-operation-response.d.ts

@@ -1,5 +1,6 @@
+import type { JsonValue } from "./json-value-types.js";
+import type { JsonObject } from "./json.js";
 import type { JsonOperationId, OperationResponses } from "./operation-responses.js";
-import type { JsonSchema } from "./response-schemas.js";
 /** Evaluate the JSON Schema keywords used by the published response contracts. */
-export declare const matchesResponseSchema: (value: unknown, schema: unknown, root: JsonSchema) => boolean;
-export declare const parseOperationResponse: <K extends JsonOperationId>(operationId: K, value: unknown) => Promise<OperationResponses[K]>;
+export declare const matchesResponseSchema: (value: JsonValue | undefined, schema: JsonValue | undefined, root: JsonObject) => boolean;
+export declare const parseOperationResponse: <K extends JsonOperationId>(operationId: K, value: JsonValue | undefined) => Promise<OperationResponses[K]>;

package/parse-operation-response.js

@@ -1,185 +1,162 @@
 import { openClientResponseEnums } from "./client-response-schema.js";
 import { MaterialGraphError } from "./errors.js";
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+import { isJsonNumber, isJsonObject, isJsonString, jsonKind } from "./json.js";
 const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const SIMPLE_TYPES = new Set([
+    "array",
+    "boolean",
+    "null",
+    "object",
+    "string",
+]);
 const matchesType = (value, type) => {
     if (Array.isArray(type)) {
         return type.some((candidate) => matchesType(value, candidate));
     }
-    switch (type) {
-        case undefined: {
-            return true;
-        }
-        case "null": {
-            return value === null;
-        }
-        case "array": {
-            return Array.isArray(value);
-        }
-        case "object": {
-            return isRecord(value);
-        }
-        case "integer": {
-            return typeof value === "number" && Number.isInteger(value);
-        }
-        case "number": {
-            return typeof value === "number" && Number.isFinite(value);
-        }
-        case "string": {
-            return typeof value === "string";
-        }
-        case "boolean": {
-            return typeof value === "boolean";
-        }
-        default: {
-            return false;
-        }
+    if (type === undefined) {
+        return true;
+    }
+    if (type === "integer") {
+        return isJsonNumber(value) && Number.isInteger(value);
+    }
+    if (type === "number") {
+        return isJsonNumber(value) && Number.isFinite(value);
     }
+    return (isJsonString(type) && SIMPLE_TYPES.has(type) && jsonKind(value) === type);
 };
 const matchesNumberKeywords = (value, schema) => {
-    if (typeof value === "number") {
-        if (typeof schema.minimum === "number" && value < schema.minimum) {
-            return false;
+    if (!isJsonNumber(value)) {
+        return true;
+    }
+    const { exclusiveMaximum, exclusiveMinimum, maximum, minimum } = schema;
+    if (isJsonNumber(minimum) && value < minimum) {
+        return false;
+    }
+    if (isJsonNumber(maximum) && value > maximum) {
+        return false;
+    }
+    if (isJsonNumber(exclusiveMinimum) && value <= exclusiveMinimum) {
+        return false;
+    }
+    return !(isJsonNumber(exclusiveMaximum) && value >= exclusiveMaximum);
+};
+const matchesStringKeywords = (value, schema) => {
+    if (!isJsonString(value)) {
+        return true;
+    }
+    const { maxLength, minLength, pattern } = schema;
+    let length = 0;
+    for (const _codePoint of value) {
+        length += 1;
+    }
+    if (isJsonNumber(minLength) && length < minLength) {
+        return false;
+    }
+    if (isJsonNumber(maxLength) && length > maxLength) {
+        return false;
+    }
+    return !(isJsonString(pattern) && !new RegExp(pattern, "u").test(value));
+};
+const matchesValueKeywords = (value, schema) => {
+    if ("const" in schema && !sameJson(value, schema.const)) {
+        return false;
+    }
+    const { enum: allowed } = schema;
+    return !(Array.isArray(allowed) &&
+        !allowed.some((candidate) => sameJson(candidate, value)));
+};
+/** Evaluates the JSON Schema keywords the published response contracts use. */
+class ResponseSchemaEvaluator {
+    #root;
+    constructor(root) {
+        this.#root = root;
+    }
+    matches(value, schema) {
+        if (schema === true || schema === false) {
+            return schema;
         }
-        if (typeof schema.maximum === "number" && value > schema.maximum) {
+        if (!isJsonObject(schema)) {
             return false;
         }
-        if (typeof schema.exclusiveMinimum === "number" &&
-            value <= schema.exclusiveMinimum) {
+        if (!this.#matchesReference(value, schema)) {
             return false;
         }
-        if (typeof schema.exclusiveMaximum === "number" &&
-            value >= schema.exclusiveMaximum) {
+        if (!matchesType(value, schema.type)) {
             return false;
         }
-    }
-    return true;
-};
-const matchesStringKeywords = (value, schema) => {
-    if (typeof value === "string") {
-        let length = 0;
-        for (const _codePoint of value) {
-            length += 1;
-        }
-        if (typeof schema.minLength === "number" && length < schema.minLength) {
+        if (!matchesValueKeywords(value, schema)) {
             return false;
         }
-        if (typeof schema.maxLength === "number" && length > schema.maxLength) {
+        if (Array.isArray(schema.anyOf) &&
+            !schema.anyOf.some((candidate) => this.matches(value, candidate))) {
             return false;
         }
-        if (typeof schema.pattern === "string" &&
-            !new RegExp(schema.pattern, "u").test(value)) {
+        if ("not" in schema && this.matches(value, schema.not)) {
             return false;
         }
+        return (matchesNumberKeywords(value, schema) &&
+            matchesStringKeywords(value, schema) &&
+            this.#matchesArrayKeywords(value, schema) &&
+            this.#matchesObjectKeywords(value, schema));
     }
-    return true;
-};
-const matchesArrayKeywords = (value, schema, root) => {
-    if (Array.isArray(value)) {
-        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+    #matchesArrayKeywords(value, schema) {
+        if (!Array.isArray(value)) {
+            return true;
+        }
+        const { items, maxItems, minItems, prefixItems } = schema;
+        if (isJsonNumber(minItems) && value.length < minItems) {
             return false;
         }
-        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+        if (isJsonNumber(maxItems) && value.length > maxItems) {
             return false;
         }
-        const prefix = Array.isArray(schema.prefixItems) ? schema.prefixItems : [];
+        const prefix = Array.isArray(prefixItems) ? prefixItems : [];
         for (const [index, item] of value.entries()) {
-            const itemSchema = index < prefix.length ? prefix[index] : schema.items;
-            if (itemSchema !== undefined &&
-                !matchesResponseSchema(item, itemSchema, root)) {
+            const itemSchema = index < prefix.length ? prefix[index] : items;
+            if (itemSchema !== undefined && !this.matches(item, itemSchema)) {
                 return false;
             }
         }
+        return true;
     }
-    return true;
-};
-const matchesObjectKeywords = (value, schema, root) => {
-    if (isRecord(value)) {
-        if (Array.isArray(schema.required) &&
-            !schema.required.every((key) => typeof key === "string" && Object.hasOwn(value, key))) {
+    #matchesObjectKeywords(value, schema) {
+        if (!isJsonObject(value)) {
+            return true;
+        }
+        const { additionalProperties, propertyNames, required } = schema;
+        if (Array.isArray(required) &&
+            !required.every((key) => isJsonString(key) && Object.hasOwn(value, key))) {
             return false;
         }
-        const properties = isRecord(schema.properties) ? schema.properties : {};
+        const properties = isJsonObject(schema.properties) ? schema.properties : {};
         for (const [key, item] of Object.entries(value)) {
-            if (schema.propertyNames !== undefined &&
-                !matchesResponseSchema(key, schema.propertyNames, root)) {
+            if (propertyNames !== undefined && !this.matches(key, propertyNames)) {
                 return false;
             }
             const property = Object.hasOwn(properties, key)
                 ? properties[key]
-                : schema.additionalProperties;
-            if (property !== undefined &&
-                !matchesResponseSchema(item, property, root)) {
+                : additionalProperties;
+            if (property !== undefined && !this.matches(item, property)) {
                 return false;
             }
         }
+        return true;
     }
-    return true;
-};
-const matchesResponseReference = (value, schema, root) => {
-    if (typeof schema.$ref === "string") {
-        if (!schema.$ref.startsWith("#/$defs/")) {
-            return false;
+    #matchesReference(value, schema) {
+        const reference = schema.$ref;
+        if (!isJsonString(reference)) {
+            return true;
         }
-        const name = schema.$ref
-            .slice(8)
-            .replaceAll("~1", "/")
-            .replaceAll("~0", "~");
-        if (!isRecord(root.$defs) ||
-            !matchesResponseSchema(value, root.$defs[name], root)) {
+        if (!reference.startsWith("#/$defs/")) {
             return false;
         }
+        const name = reference.slice(8).replaceAll("~1", "/").replaceAll("~0", "~");
+        const definitions = this.#root.$defs;
+        return isJsonObject(definitions) && this.matches(value, definitions[name]);
     }
-    return true;
-};
-const matchesResponseValue = (value, schema) => {
-    if ("const" in schema && !sameJson(value, schema.const)) {
-        return false;
-    }
-    if (Array.isArray(schema.enum) &&
-        !schema.enum.some((candidate) => sameJson(candidate, value))) {
-        return false;
-    }
-    return true;
-};
+}
 /** Evaluate the JSON Schema keywords used by the published response contracts. */
-export const matchesResponseSchema = (value, schema, root) => {
-    if (typeof schema === "boolean") {
-        return schema;
-    }
-    if (!isRecord(schema)) {
-        return false;
-    }
-    if (!matchesResponseReference(value, schema, root)) {
-        return false;
-    }
-    if (!matchesType(value, schema.type)) {
-        return false;
-    }
-    if (!matchesResponseValue(value, schema)) {
-        return false;
-    }
-    if (Array.isArray(schema.anyOf) &&
-        !schema.anyOf.some((candidate) => matchesResponseSchema(value, candidate, root))) {
-        return false;
-    }
-    if ("not" in schema && matchesResponseSchema(value, schema.not, root)) {
-        return false;
-    }
-    if (!matchesNumberKeywords(value, schema)) {
-        return false;
-    }
-    if (!matchesStringKeywords(value, schema)) {
-        return false;
-    }
-    if (!matchesArrayKeywords(value, schema, root)) {
-        return false;
-    }
-    if (!matchesObjectKeywords(value, schema, root)) {
-        return false;
-    }
-    return true;
-};
+export const matchesResponseSchema = (value, schema, root) => new ResponseSchemaEvaluator(root).matches(value, schema);
 const schemas = new Map();
 /** The operation's published schema, rather than a caller's type argument, proves its response. */
 const isOperationResponse = (operationId, value) => {
@@ -190,8 +167,8 @@ export const parseOperationResponse = async (operationId, value) => {
     let schema = schemas.get(operationId);
     if (!schema) {
         // oxlint-disable-next-line howells/no-runtime-dynamic-imports -- Load the large response schema bundle only when a response needs validation.
-        const { responseSchema } = await import("./response-schemas.js");
-        schema = responseSchema(operationId);
+        const catalog = await import("./response-schema-catalog.js");
+        schema = catalog.buildResponseSchema(operationId);
         openClientResponseEnums(schema);
         schemas.set(operationId, schema);
     }

package/resolve-color-types.d.ts

@@ -7,15 +7,15 @@ import type { VariantId } from "./identifiers.js";
 import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
 import type { OpenEnum } from "./types.js";
 /** Options for `resolveColor`. */
-export type ResolveColorOptions = {
+export interface ResolveColorOptions {
     /**
      * Sets `inScope` on each catalog variant the lookup reports. It never
      * narrows the lookup. Absent leaves every `inScope` null.
      */
     searchCatalogSubset?: SearchCatalogSubset;
-};
+}
 /** One catalog variant carrying the named paint. */
-export type ResolveColorCatalogVariant = {
+export interface ResolveColorCatalogVariant {
     variantId: VariantId;
     /** The brand exactly as stored, suspect or not. */
     brand: {
@@ -25,7 +25,7 @@ export type ResolveColorCatalogVariant = {
     };
     /** Whether the variant is in the requested scope; null when none was asked for. */
     inScope: boolean | null;
-};
+}
 /**
  * Whether the named paint is a variant in the catalog. Exact, global, and
  * never narrowed by `searchCatalogSubset`, and run only for a `brand` library hit.
@@ -43,7 +43,7 @@ export type ResolveColorVariant = ({
     status: "not-looked-up";
     reason: OpenEnum<"reference-color" | "descriptive-color" | "no-paint-identity" | "generic-color" | "several-paints">;
 };
-export type ResolveColorResponse = {
+export interface ResolveColorResponse {
     /** Examples within the governed range. They do not replace its representative or bounds. */
     rangeSamples?: string[];
     /** Explicit brand choices for an ambiguous paint name. Never selected automatically. */
@@ -73,4 +73,4 @@ export type ResolveColorResponse = {
         /** The catalog lookup for the name. Absent from servers that predate it. */
         variant?: ResolveColorVariant;
     } | null;
-};
+}

package/resolve-variant-types.d.ts

@@ -13,15 +13,15 @@
  * 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 ResolveVariantInput = {
+export interface ResolveVariantInput {
     url?: string;
     materialBankId?: string;
     code?: string;
     brandId?: string;
     labels?: string[];
-};
+}
 /** One identified, placed or bounded-candidate subject. */
-export type ResolveVariantSubject = {
+export interface ResolveVariantSubject {
     kind: "variant" | "brand";
     id: string;
     name: string;
@@ -30,23 +30,23 @@ export type ResolveVariantSubject = {
         id: string;
         name: string;
     };
-};
+}
 /** What stood behind an outcome. Exact and scoreless: never a similarity guess. */
-export type ResolveVariantEvidence = {
+export interface ResolveVariantEvidence {
     kind: "brand-url" | "brand-homepage" | "brand-code" | "material-bank-id" | "visible-label";
     url?: string;
     detail: string;
-};
+}
 /** The submitted URL, normalized, and the steps that normalization took. Absent for a code-only call. */
-export type ResolveVariantReceipt = {
+export interface ResolveVariantReceipt {
     submittedUrl: string;
     normalizedUrl: string;
     normalizationSteps: string[];
-};
-type ResolveVariantOutputBase = {
+}
+interface ResolveVariantOutputBase {
     evidence: ResolveVariantEvidence[];
     receipt?: ResolveVariantReceipt;
-};
+}
 /**
  * Why nothing was resolved. Absent and empty differ: this names what was
  * looked for and not found, never a similarity guess.

package/response-schema-catalog.d.ts

@@ -0,0 +1,8 @@
+import type { JsonObject } from "./json.js";
+export declare const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+/**
+ * The success-response schema for one operation, self-contained and carrying
+ * only the definitions it reaches. Each call returns a fresh copy, so a caller
+ * that annotates or mutates it cannot change what the next caller gets.
+ */
+export declare const buildResponseSchema: (operationId: string) => JsonObject;

package/response-schema-catalog.js

@@ -0,0 +1,82 @@
+/**
+ * The generated response-schema catalog, parsed once on first use. It is its
+ * own module because the catalog is large: importing the client does not load
+ * it.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { isJsonObject, isJsonString, parseJson } from "./json.js";
+import { RESPONSE_SCHEMA_CATALOG_JSON } from "./response-schemas.generated.js";
+export const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+const DEFINITION_PREFIX = "#/$defs/";
+const isJsonSchemaMap = (value) => isJsonObject(value) && Object.values(value).every(isJsonObject);
+const isCatalog = (value) => isJsonObject(value) &&
+    isJsonSchemaMap(value.definitions) &&
+    isJsonSchemaMap(value.operations);
+let parsedCatalog;
+const loadCatalog = () => {
+    if (parsedCatalog === undefined) {
+        const parsed = parseJson(RESPONSE_SCHEMA_CATALOG_JSON);
+        if (!isCatalog(parsed)) {
+            throw MaterialGraphError.unexpected("The response schema catalog is malformed");
+        }
+        parsedCatalog = parsed;
+    }
+    return parsedCatalog;
+};
+/** Add every definition `value` reaches, transitively, to `into`. */
+const collectReferences = (catalog, value, into) => {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectReferences(catalog, item, into);
+        }
+        return;
+    }
+    if (!isJsonObject(value)) {
+        return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "$ref" &&
+            isJsonString(child) &&
+            child.startsWith(DEFINITION_PREFIX)) {
+            const name = child
+                .slice(DEFINITION_PREFIX.length)
+                .replaceAll("~1", "/")
+                .replaceAll("~0", "~");
+            if (!into.has(name)) {
+                into.add(name);
+                collectReferences(catalog, catalog.definitions[name], into);
+            }
+        }
+        else {
+            collectReferences(catalog, child, into);
+        }
+    }
+};
+/**
+ * The success-response schema for one operation, self-contained and carrying
+ * only the definitions it reaches. Each call returns a fresh copy, so a caller
+ * that annotates or mutates it cannot change what the next caller gets.
+ */
+export const buildResponseSchema = (operationId) => {
+    const catalog = loadCatalog();
+    const root = Object.hasOwn(catalog.operations, operationId)
+        ? catalog.operations[operationId]
+        : undefined;
+    if (root === undefined || !isJsonObject(root)) {
+        throw MaterialGraphError.unexpected(`No response schema for operation: ${operationId}`);
+    }
+    const names = new Set();
+    collectReferences(catalog, root, names);
+    const definitions = {};
+    for (const name of [...names].toSorted()) {
+        const definition = catalog.definitions[name];
+        if (definition !== undefined) {
+            definitions[name] = definition;
+        }
+    }
+    const schema = { $schema: JSON_SCHEMA_DIALECT, ...root };
+    if (names.size > 0) {
+        schema.$defs = definitions;
+    }
+    return structuredClone(schema);
+};

package/response-schemas.d.ts

@@ -1,17 +1,46 @@
+/**
+ * Runtime response contracts: the JSON Schema of each operation's success body.
+ *
+ * The schemas are the producer's own. They are projected from the served
+ * OpenAPI document, whose response bodies are generated from the Zod contracts
+ * the routes validate against, so a consumer never has to re-describe a large,
+ * partly open payload and watch it drift. Hand one to anything that takes a
+ * JSON Schema, such as a Mastra tool's `outputSchema`:
+ *
+ * ```ts
+ * import { responseSchema } from "@instruments/materialgraph/response-schemas";
+ *
+ * createTool({ outputSchema: responseSchema("search_variants"), … });
+ * ```
+ *
+ * Keyed by OpenAPI `operationId`, the same id `SDK_OPERATIONS` pairs with each
+ * client method. Schemas are JSON Schema 2020-12 and describe the parsed body
+ * the client method returns.
+ *
+ * Objects accept properties the schema does not declare, so a field the API
+ * adds later never makes a pinned consumer reject a live response; enums and
+ * constants stay closed. That is why these are more lenient than the WebMCP
+ * `outputSchema`s, which describe what the API sends rather than what a
+ * consumer should tolerate.
+ *
+ * This is its own entry point because the catalog is large; importing the
+ * client does not load it, and it is parsed on the first `responseSchema()`
+ * call rather than on import.
+ */
+import { JSON_SCHEMA_DIALECT } from "./response-schema-catalog.js";
 import type { RESPONSE_SCHEMA_OPERATION_IDS } from "./response-schemas.generated.js";
 export { RESPONSE_SCHEMA_API_VERSION, RESPONSE_SCHEMA_OPERATION_IDS, } from "./response-schemas.generated.js";
 /** Every operation {@link responseSchema} answers for. */
 export type ResponseSchemaOperationId = (typeof RESPONSE_SCHEMA_OPERATION_IDS)[number];
 /** A JSON Schema document or subschema, as plain JSON. */
-export type JsonSchema = {
+export interface JsonSchema {
     [keyword: string]: unknown;
-};
+}
 /** A self-contained schema: every `$ref` resolves inside its own `$defs`. */
 export type ResponseJsonSchema = JsonSchema & {
     $schema: typeof JSON_SCHEMA_DIALECT;
     $defs?: Record<string, JsonSchema>;
 };
-declare const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
 /**
  * The success-response schema for one operation, self-contained and carrying
  * only the definitions it reaches. Each call returns a fresh copy, so a caller

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;