@instruments/materialgraph 3.0.2 → 3.2.0

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