@instruments/materialgraph 3.1.0 → 3.3.0

package/response-schemas.js

@@ -27,86 +27,14 @@
  * client does not load it, and it is parsed on the first `responseSchema()`
  * call rather than on import.
  */
-import { MaterialGraphError } from "./errors.js";
-import { RESPONSE_SCHEMA_CATALOG_JSON } from "./response-schemas.generated.js";
+import { JSON_SCHEMA_DIALECT, buildResponseSchema, } from "./response-schema-catalog.js";
 export { RESPONSE_SCHEMA_API_VERSION, RESPONSE_SCHEMA_OPERATION_IDS, } from "./response-schemas.generated.js";
-const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
-const DEFINITION_PREFIX = "#/$defs/";
-const isJsonSchemaMap = (value) => typeof value === "object" &&
-    value !== null &&
-    Object.values(value).every((schema) => typeof schema === "object" && schema !== null && !Array.isArray(schema));
-const isCatalog = (value) => typeof value === "object" &&
-    value !== null &&
-    "definitions" in value &&
-    isJsonSchemaMap(value.definitions) &&
-    "operations" in value &&
-    isJsonSchemaMap(value.operations);
-let parsedCatalog;
-const loadCatalog = () => {
-    if (parsedCatalog === undefined) {
-        const parsed = JSON.parse(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 (typeof value !== "object" || value === null) {
-        return;
-    }
-    for (const [key, child] of Object.entries(value)) {
-        if (key === "$ref" &&
-            typeof child === "string" &&
-            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 responseSchema = (operationId) => {
-    const catalog = loadCatalog();
-    const root = Object.hasOwn(catalog.operations, operationId)
-        ? catalog.operations[operationId]
-        : undefined;
-    if (root === undefined) {
-        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,
-        ...(names.size > 0 ? { $defs: definitions } : {}),
-    };
-    return structuredClone(schema);
-};
+export const responseSchema = (operationId) => ({
+    ...buildResponseSchema(operationId),
+    $schema: JSON_SCHEMA_DIALECT,
+});

package/schema-resource-types.d.ts

@@ -11,13 +11,13 @@ export declare const SCHEMA_RESOURCE_OPERATION_IDS: {
     readonly valueDictionaries: "list_schema_value_dictionaries";
 };
 export type SchemaResourceRequest = SchemaResource;
-export type SchemaLifecycle = {
+export interface SchemaLifecycle {
     status: OpenEnum<"draft" | "active" | "deprecated">;
     introducedIn: string;
     deprecatedIn?: string;
     supersededBy?: string;
-};
-export type SchemaExternalMapping = {
+}
+export interface SchemaExternalMapping {
     target: OpenEnum<"schema_org" | "ifc_pset" | "bsdd" | "iso_23387" | "eclass" | "gs1_gdm" | "gdsn" | "etim" | "uniclass">;
     targetPath: string;
     mappingType: OpenEnum<"direct" | "transform" | "derived" | "classification" | "semantic">;
@@ -27,9 +27,9 @@ export type SchemaExternalMapping = {
      */
     matchStrength?: SchemaMatchStrength;
     notes?: string;
-};
+}
 export type SchemaMatchStrength = OpenEnum<"exact" | "close" | "broad" | "narrow" | "related">;
-export type SchemaValueDictionaryTerm = {
+export interface SchemaValueDictionaryTerm {
     id: string;
     label: string;
     aliases?: string[];
@@ -37,21 +37,21 @@ export type SchemaValueDictionaryTerm = {
     externalMappings?: SchemaExternalMapping[];
     semanticId: string;
     lifecycle: SchemaLifecycle;
-};
-export type SchemaValueDictionaryItem = {
+}
+export interface SchemaValueDictionaryItem {
     id: string;
     name: string;
     description: string;
     terms: SchemaValueDictionaryTerm[];
     semanticId: string;
     lifecycle: SchemaLifecycle;
-};
-export type SchemaResourceItemMap = {
+}
+export interface SchemaResourceItemMap {
     valueDictionaries: SchemaValueDictionaryItem;
-};
-export type SchemaResourceResponse<K extends SchemaResource = SchemaResource> = {
+}
+export interface SchemaResourceResponse<K extends SchemaResource = SchemaResource> {
     kind: K;
     schemaVersion: string;
     items: SchemaResourceItemMap[K][];
     totalCount: number;
-};
+}

package/search-catalog-subset-types.d.ts

@@ -50,8 +50,8 @@ export type SearchCatalogSubset = OpenEnum<"samplizeOrderable" | "all" | "design
  * the counts: a short page under a scope is a small SCOPED corpus, never a
  * truncated one.
  */
-export type SearchCatalogSubsetReceipt = {
+export interface SearchCatalogSubsetReceipt {
     scope: SearchCatalogSubset;
     /** What the scope admits, in one sentence, for a human reader. */
     description: string;
-};
+}

package/search-variants-types.d.ts

@@ -10,12 +10,12 @@
 import type { ColorRangeCondition, FilterGroups, ListVariantsInclude, ListVariantsOutput, OptionalFilterGroups } from "./list-variants-types.js";
 import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
 /** Switches one of a previous answer's `choices`: its `handle`, and the `group` and `id` of the alternative to read it as. */
-export type SearchVariantsSelection = {
+export interface SearchVariantsSelection {
     group: string;
     handle: string;
     id: string;
-};
-export type SearchVariantsInput = {
+}
+export interface SearchVariantsInput {
     /** Attribute ids to project under each item's `specifications`, as `listVariants()` takes. */
     attributes?: string[];
     /** The previous page's `pageInfo.endCursor`. Tied to the vocabulary version the query was read against, and not a `listVariants()` cursor. */
@@ -32,12 +32,12 @@ export type SearchVariantsInput = {
     searchCatalogSubset?: SearchCatalogSubset;
     /** Up to eight choices to switch, from the previous answer's `choices`. */
     selections?: SearchVariantsSelection[];
-};
+}
 /**
  * What became of one phrase of the query. `filter` narrowed the page,
  * `preference` only ranked it, `not_applied` did neither and `note` says why.
  */
-export type SearchVariantsUnderstood = {
+export interface SearchVariantsUnderstood {
     applied: "filter" | "preference" | "not_applied";
     /** The parser's condition id. */
     id: string;
@@ -47,33 +47,33 @@ export type SearchVariantsUnderstood = {
     note?: string;
     /** The query words it came from. */
     text: string;
-};
+}
 /** One reading of an ambiguous phrase. */
-export type SearchVariantsReading = {
+export interface SearchVariantsReading {
     group: string;
     id: string;
     kind: string;
     label: string;
     /** Variants in search scope that hold this reading. */
     variants?: number;
-};
+}
 /** On an empty page: a change to the next call that returns variants. */
-export type SearchVariantsSuggestion = {
+export interface SearchVariantsSuggestion {
     /** The `leaveOut` entries to send. */
     leaveOut?: string[];
     note: string;
     /** Variants the search returns with this change. */
     variants: number;
-};
+}
 /** A phrase with more than one meaning: the reading used, and the others a caller may switch to by `handle`. */
-export type SearchVariantsChoice = {
+export interface SearchVariantsChoice {
     alternatives: SearchVariantsReading[];
     basis: string;
     handle: string;
     reason: string;
     selected: SearchVariantsReading;
     text: string;
-};
+}
 /** The `listVariants()` page, with how the words were read beside it. */
 export type SearchVariantsOutput = ListVariantsOutput & {
     choices?: SearchVariantsChoice[];

package/source-material-types.d.ts

@@ -30,11 +30,11 @@ export type FileInput = Blob | {
  * plain-text/markdown, and images (≥1, ≤16). The server classifies each file
  * and assigns its receipt {@link SourceMaterialReceiptFile.role}.
  */
-export type UploadSourceMaterialInput = {
+export interface UploadSourceMaterialInput {
     files: FileInput[];
-};
+}
 /** One stored file in an upload receipt. */
-export type SourceMaterialReceiptFile = {
+export interface SourceMaterialReceiptFile {
     /** The stored file id (`smf_…`). Opaque — the prefix is a reading aid, not a contract. */
     sourceId: SourceFileId;
     /**
@@ -50,10 +50,10 @@ export type SourceMaterialReceiptFile = {
     bytes: number;
     /** PDF page count; null for images. */
     pages: number | null;
-};
+}
 /** The `201` receipt from `POST /api/v1/source-material`. */
-export type SourceMaterialBatchReceipt = {
+export interface SourceMaterialBatchReceipt {
     /** The stored batch id (`smb_…`). Opaque. */
     batchId: BatchId;
     sources: SourceMaterialReceiptFile[];
-};
+}

package/source-material.js

@@ -4,34 +4,7 @@
  */
 import { MaterialGraphError } from "./errors.js";
 import { findSdkOperation, operationPath } from "./operations.js";
-const hasSourceIdentity = (source) => typeof source === "object" &&
-    source !== null &&
-    "sourceId" in source &&
-    typeof source.sourceId === "string" &&
-    "role" in source &&
-    typeof source.role === "string" &&
-    "filename" in source &&
-    typeof source.filename === "string" &&
-    "mediaType" in source &&
-    typeof source.mediaType === "string";
-const hasSourceMeasurements = (source) => typeof source === "object" &&
-    source !== null &&
-    "sha256" in source &&
-    typeof source.sha256 === "string" &&
-    "bytes" in source &&
-    typeof source.bytes === "number" &&
-    "pages" in source &&
-    (source.pages === null || typeof source.pages === "number");
-const isSourceReceipt = (value) => typeof value === "object" &&
-    value !== null &&
-    "batchId" in value &&
-    typeof value.batchId === "string" &&
-    "sources" in value &&
-    Array.isArray(value.sources) &&
-    value.sources.every((source) => typeof source === "object" &&
-        source !== null &&
-        hasSourceIdentity(source) &&
-        hasSourceMeasurements(source));
+import { parseOperationResponse } from "./parse-operation-response.js";
 const sdkOperation = (operationId) => {
     const match = findSdkOperation(operationId);
     if (!match) {
@@ -85,8 +58,5 @@ export const uploadSourceMaterial = async (transport, input, signal) => {
         signal,
         url,
     });
-    if (!isSourceReceipt(parsed)) {
-        throw MaterialGraphError.unexpected("MaterialGraph source-material upload returned an invalid receipt");
-    }
-    return parsed;
+    return await parseOperationResponse("upload_source_material", parsed);
 };

package/types.d.ts

@@ -29,13 +29,13 @@ import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
 export type OpenEnum<T extends string> = T | (string & Record<never, never>);
 export type { JsonValue } from "./json-value-types.js";
 /** OKLab triple. */
-export type OklabTriple = {
+export interface OklabTriple {
     l: number;
     a: number;
     b: number;
-};
+}
 /** The material's dominant-color block (tile/detail projections). */
-export type MaterialColor = {
+export interface MaterialColor {
     dominantHex: string | null;
     hsl: {
         h: number;
@@ -45,25 +45,23 @@ export type MaterialColor = {
     oklab: OklabTriple | null;
     chroma: number | null;
     vibrancy: number | null;
-};
+}
 /** Where the served image came from. */
 export type ImageSource = OpenEnum<"r2" | "origin">;
 export type { MaterialAvailability, MaterialTile } from "./material-types.js";
-export type DemandMomentum = {
-    state: OpenEnum<"rising" | "fading" | "stable" | "emerging" | "insufficient_volume">;
-    percentChange: number | null;
-    trailingSpecCount: number;
-    priorSpecCount: number;
-};
-export type CompanionDemand = {
-    specCount: number;
-    projectCount: number;
-    momentum: DemandMomentum | null;
-};
-export type ProjectTypeShare = {
+/** How much a companion is itself sampled; never a count. */
+export interface CompanionDemand {
+    /** Share of its category's variants sampled as much or less, 1 to 100. */
+    samplePercentile: number;
+    /** Null when the year before cannot be shown. */
+    trend: OpenEnum<"rising" | "steady" | "falling"> | null;
+    /** This year against the year before; 0.4 is 40% more. Null with `trend`. */
+    change: number | null;
+}
+export interface ProjectTypeShare {
     projectType: string;
     projectCount: number;
-};
+}
 /**
  * A pairing item from the behavioral arm — real order evidence, or board
  * curation when this seed has no order edges.
@@ -80,7 +78,7 @@ export type ProjectTypeShare = {
  *
  * See {@link ColorPairing} for the third, non-evidential arm.
  */
-export type CospecPairing = {
+export interface CospecPairing {
     /** The evidence tier. `cospec` = orders; `considered` = boards. Read it before phrasing. */
     source: "cospec" | "considered";
     /**
@@ -124,7 +122,7 @@ export type CospecPairing = {
     topProjectTypes: ProjectTypeShare[];
     /** Graph-owned color ranking facts, present only for an explicitly ordered rail. */
     ranking?: PairingRanking;
-};
+}
 /**
  * A pairing item topped up from color palette-similarity — a LOOK-ALIKE, not
  * evidence. Nobody ordered these together and nobody boarded them together; the
@@ -144,14 +142,14 @@ export type ColorPairing = {
     ranking?: PairingRanking;
 } & MaterialTile;
 export type PairingOrderMode = "relevance" | "lightness_asc" | "lightness_desc";
-export type PairingRanking = {
+export interface PairingRanking {
     anchorColorSimilarity: number | null;
     lightness: number | null;
     anchorColorSimilarityMeasurable: boolean;
     lightnessMeasurable: boolean;
     basis: OpenEnum<"dominant_color_oklab">;
-};
-export type PairingOrdering = {
+}
+export interface PairingOrdering {
     requested: OpenEnum<PairingOrderMode>;
     applied: OpenEnum<PairingOrderMode>;
     direction: OpenEnum<"ascending" | "descending">;
@@ -163,14 +161,14 @@ export type PairingOrdering = {
     };
     missingValues: OpenEnum<"last">;
     tieBreak: OpenEnum<"variantId_asc">;
-};
+}
 /**
  * One pairing, discriminated by `source` into three tiers of very different
  * strength: `cospec` (real orders) > `considered` (board activity) > `color`
  * (palette look-alike). Branch on `source` before you write a sentence about it.
  */
 export type PairingItem = CospecPairing | ColorPairing;
-export type PairingsResponse = {
+export interface PairingsResponse {
     seed: MaterialTile;
     /** A rail, not a ranked corpus — mixed evidence tiers, capped by `limit`. */
     items: PairingItem[];
@@ -191,7 +189,7 @@ export type PairingsResponse = {
     ordering?: PairingOrdering;
     /** Opaque continuation bound to the seed, filters, corpus, and order. */
     nextCursor?: Cursor;
-};
+}
 /**
  * How a {@link AttributeListItem} matched the query. Declared here rather than
  * imported: this package is published, so it may not reach across into
@@ -199,7 +197,7 @@ export type PairingsResponse = {
  * of truth this wire type tracks. `method` is deliberately open - a server
  * that grows a method must not break an older client.
  */
-export type AttributeMatch = {
+export interface AttributeMatch {
     method: OpenEnum<"exact" | "alias" | "fuzzy" | "vector">;
     /** The id, name or alias that matched, or null for a match by meaning. */
     matchedText: string | null;
@@ -212,9 +210,9 @@ export type AttributeMatch = {
      * when the attribute was found through one of its values.
      */
     valueId?: string;
-};
+}
 /** One attribute definition on a `listAttributes()` page. */
-export type AttributeListItem = {
+export interface AttributeListItem {
     id: string;
     name: string;
     description: string;
@@ -230,14 +228,14 @@ export type AttributeListItem = {
     match?: AttributeMatch;
     /** Live variants in the requested categories stating it; absent without `categoryIds`. */
     statedBy?: number;
-};
+}
 /** An attribute a block-scoped `listAttributes()` query missed, named with its real blocks. */
-export type OutsideScopeAttribute = {
+export interface OutsideScopeAttribute {
     id: string;
     name: string;
     blockIds: string[];
-};
-export type ListAttributesResult = {
+}
+export interface ListAttributesResult {
     items: AttributeListItem[];
     /** Page one only: matches outside `blockIds` ranking above the best item. Absent when the check did not apply. */
     outsideScope?: OutsideScopeAttribute[];
@@ -247,16 +245,16 @@ export type ListAttributesResult = {
         endCursor: string | null;
         hasNextPage: boolean;
     };
-};
+}
 export type { ResolveValueCandidate, ValueResolution, } from "./catalog-discovery-types.js";
 export type { ResolveColorOptions, ResolveColorCatalogVariant, ResolveColorVariant, ResolveColorResponse, } from "./resolve-color-types.js";
 export type { BySpecVerdictState, BySpecVerdictCell, BySpecVerdict, MaterialVerdict, BySpecUnresolvedCriterion, } from "./by-spec-types.js";
-export type WhoamiResponse = {
+export interface WhoamiResponse {
     principal: string;
     scopes: string[];
-};
+}
 /** Options for a pairings read. */
-export type PairingsOptions = {
+export interface PairingsOptions {
     /** Comma-separated coarse category display names; filters both arms. */
     categories?: string;
     /** Page size, 1–24 inclusive (default 12). The server rejects (400), not clamps, values outside this range. */
@@ -269,9 +267,9 @@ export type PairingsOptions = {
     searchCatalogSubset?: SearchCatalogSubset;
     /** The previous response's `nextCursor`, passed back verbatim. */
     cursor?: Cursor;
-};
+}
 /** Options for `listAttributes()` (GET `/api/v1/catalog/attributes`). */
-export type ListAttributesOptions = {
+export interface ListAttributesOptions {
     /** An attribute id, name, misspelling or meaning, e.g. "reduces echo". */
     query?: string;
     /** Keep attributes in any of these blocks. */
@@ -284,8 +282,8 @@ export type ListAttributesOptions = {
     limit?: number;
     /** `pageInfo.endCursor` from the previous page, with the same query and scope. */
     cursor?: string;
-};
-export type ExtractedPalette = {
+}
+export interface ExtractedPalette {
     colors: {
         hex: string;
         name: string;
@@ -298,14 +296,14 @@ export type ExtractedPalette = {
         oklch: string;
     } | null;
     mood: string;
-};
-export type ExtractPaletteResponse = {
+}
+export interface ExtractPaletteResponse {
     palette: ExtractedPalette | null;
-};
+}
 /** Body for `POST /api/v1/search/palettes/extract`. */
-export type ExtractPaletteInput = {
+export interface ExtractPaletteInput {
     /** The query image as a data URI or bare base64 string. */
     image: string;
     /** Max palette swatches to return (default 6). */
     max?: number;
-};
+}

package/webmcp.d.ts

@@ -1,17 +1,23 @@
+/** A JSON value, as a tool's input and output schemas are written. */
+export type WebMcpJson = string | number | boolean | null | readonly WebMcpJson[] | WebMcpJsonObject;
+/** A JSON object whose every member is a JSON value. */
+export interface WebMcpJsonObject {
+    readonly [key: string]: WebMcpJson;
+}
 /** Canonical operation contracts. Consumers validate both boundaries and supply their own transport. */
-export type WebMcpToolContract = {
+export interface WebMcpToolContract {
     readonly name: "search";
     readonly operationId: string;
     readonly path: string;
     readonly method: "POST";
     readonly description: string;
-    readonly inputSchema: Readonly<Record<string, unknown>>;
-    readonly outputSchema: Readonly<Record<string, unknown>>;
+    readonly inputSchema: WebMcpJsonObject;
+    readonly outputSchema: WebMcpJsonObject;
     readonly annotations: {
         readonly readOnlyHint: boolean;
         readonly untrustedContentHint: boolean;
     };
     readonly requiresVisibleConfirmation: boolean;
     readonly requiredHeaders: readonly string[];
-};
+}
 export { WEBMCP_TOOLS } from "./webmcp.generated.js";