@instruments/materialgraph 3.0.2 → 3.2.0

package/association-types.d.ts

@@ -22,24 +22,24 @@ import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
  * score or used to rank. Declared associations carry no ranking at all: that is
  * the point of them.
  */
-export type DeclaredProvenance = {
+export interface DeclaredProvenance {
     /** The stored convention value (0.9 today). Never a per-edge measurement. */
     confidence: number;
     /** The brand enumerated this association in its own catalog data. */
     basis: "manufacturer_declared";
     /** The provenance recorded on the edge - the brand catalog feed. */
     source: "warehouse";
-};
+}
 /** The material the question was asked about, resolved to its identity. */
-export type DeclaredAssociationSubject = {
+export interface DeclaredAssociationSubject {
     variantId: VariantId;
     brand: string;
     product: string;
     /** The variant's own name; null when it is unnamed. */
     variantName: string | null;
-};
+}
 /** One declared association, plus why it is believed. */
-export type DeclaredAssociation = {
+export interface DeclaredAssociation {
     variantId: VariantId;
     brand: string;
     product: string;
@@ -65,7 +65,7 @@ export type DeclaredAssociation = {
      * pages. Absent when the product has no eligible variant.
      */
     colorwayCount?: number;
-};
+}
 /**
  * One page of declared associations.
  *
@@ -74,7 +74,7 @@ export type DeclaredAssociation = {
  * is the whole set for this subject, direction and corpus scope. A page is not a
  * corpus — walk `nextCursor` before making any claim about the full set.
  */
-export type DeclaredAssociationsResponse = {
+export interface DeclaredAssociationsResponse {
     subject: DeclaredAssociationSubject;
     /**
      * Constant discriminator. Its presence is how a caller tells a declared fact
@@ -88,9 +88,9 @@ export type DeclaredAssociationsResponse = {
     returnedCount: number;
     /** Present only when another page exists; pass back verbatim as `cursor`. */
     nextCursor?: Cursor;
-};
+}
 /** Options for a declared-association read. */
-export type AssociatedOptions = {
+export interface AssociatedOptions {
     /**
      * Page size, 1–48 inclusive (default 24). The server rejects (400), not
      * clamps, values outside this range.
@@ -111,7 +111,7 @@ export type AssociatedOptions = {
      * different one is a 400, never a silently different page.
      */
     cursor?: Cursor;
-};
+}
 export type ApplicabilitySubject = {
     kind: "product";
     id: string;
@@ -120,15 +120,15 @@ export type ApplicabilitySubject = {
     id: VariantId;
 };
 export type ApplicabilityCoverageState = "available" | "partial" | "none_declared" | "not_ingested" | "source_not_applicable" | "unavailable";
-export type ApplicabilityCoverage = {
+export interface ApplicabilityCoverage {
     state: ApplicabilityCoverageState;
     countKind: "exact" | "partial";
     declaredCount: number | null;
     sourceAuthority: string;
     sourceLocator: string;
     sourceRevision: string;
-};
-export type ApplicabilityFact = {
+}
+export interface ApplicabilityFact {
     id: string;
     subject: ApplicabilitySubject;
     finish: {
@@ -144,8 +144,8 @@ export type ApplicabilityFact = {
         revision: string;
     };
     lifecycle: "active";
-};
-export type ApplicabilitySourceEntry = {
+}
+export interface ApplicabilitySourceEntry {
     scope: {
         sourceAuthority: string;
         sourceLocator: string;
@@ -158,8 +158,8 @@ export type ApplicabilitySourceEntry = {
     facts: ApplicabilityFact[];
     /** Source endpoints that could not be resolved during reconciliation. */
     unresolved: UnresolvedApplicabilityEndpoint[];
-};
-export type UnresolvedApplicabilityEndpoint = {
+}
+export interface UnresolvedApplicabilityEndpoint {
     subjectLocator: string;
     subjectKind: "product" | "variant" | "unknown";
     finishLocator: string;
@@ -171,14 +171,14 @@ export type UnresolvedApplicabilityEndpoint = {
         locator: string;
         revision: string;
     };
-};
+}
 /** Source-grained response; sources are never merged or given hidden precedence. */
-export type ApplicabilityResponse = {
+export interface ApplicabilityResponse {
     kind: "manufacturer_declared_applicability";
     requestedSubject: ApplicabilitySubject;
     direction: "forward" | "reverse";
     sources: ApplicabilitySourceEntry[];
-};
+}
 export type ApplicabilityOptions = {
     subjectKind: "product";
     subjectId: string;

package/brand-types.d.ts

@@ -4,7 +4,7 @@
  * `list_brands` tool and the `mg brand list` command take.
  */
 import type { SearchCatalogSubset } from "./search-catalog-subset-types.js";
-export type BrandsOptions = {
+export interface BrandsOptions {
     /**
      * A brand name, alias or misspelling, e.g. `"Kvadrat"`. Omit to browse the
      * list by name. Every brand the text matches comes back, so an ambiguous name
@@ -26,8 +26,8 @@ export type BrandsOptions = {
     limit?: number;
     /** The previous page's `pageInfo.endCursor`, with the same `query`, `categoryId` and `searchCatalogSubset`. */
     cursor?: string;
-};
-export type BrandItem = {
+}
+export interface BrandItem {
     /**
      * The brand's slug: the value `listVariants()`' `brand` filter and
      * `resolveVariant()`' `brandId` take. Never a display name.
@@ -36,8 +36,8 @@ export type BrandItem = {
     name: string;
     /** The brand's homepage, or null when none is on record. */
     website: string | null;
-};
-export type ListBrandsPage = {
+}
+export interface ListBrandsPage {
     /** THIS PAGE. Follow `pageInfo.endCursor` for the rest; a page is not a total. */
     items: BrandItem[];
     pageInfo: {
@@ -45,4 +45,4 @@ export type ListBrandsPage = {
         endCursor: string | null;
         hasNextPage: boolean;
     };
-};
+}

package/by-spec-types.d.ts

@@ -22,7 +22,7 @@ export type BySpecVerdictState = "matched" | "deviated" | "failed" | "unverified
  * Hand-mirrors the `AttributeVerdict` contract from `@materialgraph/contracts`;
  * the OpenAPI `CatalogBySpecResponse` schema is the source of truth on the wire.
  */
-export type BySpecVerdictCell = {
+export interface BySpecVerdictCell {
     attributeId: string;
     state: BySpecVerdictState;
     strength: "required" | "preferred";
@@ -57,7 +57,7 @@ export type BySpecVerdictCell = {
      *  - `basis_unmet` — the value's source is weaker than the criterion demanded.
      */
     trustGap: "below_confidence" | "basis_unmet" | null;
-};
+}
 /**
  * A match's full report card: every cell, the rolled-up grade, weakest confidence.
  *
@@ -70,11 +70,11 @@ export type BySpecVerdictCell = {
  * `minConfidence` is the WEAKEST cell's confidence — the honest ceiling on the
  * whole card, not an average. Quote it alongside the grade.
  */
-export type BySpecVerdict = {
+export interface BySpecVerdict {
     cells: BySpecVerdictCell[];
     grade: "meets_all" | "close" | "hard_no";
     minConfidence: number | null;
-};
+}
 /**
  * The verdict a materials-search hit carries (MG-625). It IS the shared
  * {@link BySpecVerdict} shape — the single CandidateVerdict mirror — aliased here
@@ -99,7 +99,7 @@ export type MaterialVerdict = BySpecVerdict;
  * EVERY miss is reported, not just the first, so one round trip is enough to fix
  * a whole spec.
  */
-export type BySpecUnresolvedCriterion = {
+export interface BySpecUnresolvedCriterion {
     /** The parsed attribute id, after the route's surrounding-whitespace trim. */
     attributeId: string;
     /** The parsed value — never overwritten by the attribute id when that id is unknown. */
@@ -108,4 +108,4 @@ export type BySpecUnresolvedCriterion = {
     reason?: "unknown_attribute_or_term" | "not_a_specification";
     /** Ranked candidates for whichever half failed. See {@link ValueResolution}. */
     resolution: ValueResolution;
-};
+}

package/catalog-discovery-types.d.ts

@@ -11,7 +11,7 @@ import type { OpenEnum } from "./types.js";
  * first: `exact_id` > `exact_alias` > `lexical` > `semantic`. A `semantic` hit
  * is a guess worth confirming, not an equivalence.
  */
-export type ResolveValueCandidate = {
+export interface ResolveValueCandidate {
     id: string;
     label: string;
     dictionaryId?: string;
@@ -19,7 +19,7 @@ export type ResolveValueCandidate = {
     tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
     /** Present only for a color_family candidate resolved via the colorscope fallback. */
     via?: OpenEnum<"colorscope">;
-};
+}
 /**
  * The resolver's verdict on ONE free-text token — the single shape every
  * resolving surface speaks, so a caller learns to read it once. Carried per bad
@@ -40,10 +40,10 @@ export type ResolveValueCandidate = {
  * `query` is the trimmed token that was actually resolved, which is how you tell
  * WHICH half of a failed `attribute:value` pair was the problem.
  */
-export type ValueResolution = {
+export interface ValueResolution {
     status: OpenEnum<"resolved" | "ambiguous" | "unresolved">;
     query: string;
     best: ResolveValueCandidate | null;
     candidates: ResolveValueCandidate[];
     recommendedAction: OpenEnum<"use_best" | "choose_from_candidates" | "ask_user" | "none_found">;
-};
+}

package/categories-client.d.ts

@@ -19,9 +19,9 @@ import type { CategoriesGetResult, CategoriesListInput, CategoriesListResult } f
 import type { QueryParams } from "./http-transport.js";
 import type { JsonOperationId, OperationResponses } from "./operation-responses.js";
 /** The client's own request primitive, handed down so this file owns no transport. */
-export type CategoriesTransport = {
-    get<K extends JsonOperationId>(operationId: K, query?: QueryParams, signal?: AbortSignal, pathParams?: Readonly<Record<string, string>>): Promise<OperationResponses[K]>;
-};
+export interface CategoriesTransport {
+    get: <K extends JsonOperationId>(operationId: K, query?: QueryParams, signal?: AbortSignal, pathParams?: Readonly<Record<string, string>>) => Promise<OperationResponses[K]>;
+}
 export declare class CategoriesClient {
     #private;
     constructor(transport: CategoriesTransport);

package/category-types.d.ts

@@ -12,22 +12,22 @@
  */
 import type { OpenEnum } from "./types.js";
 /** A category named by id, as in `ancestors` and `children`. */
-export type CategoryRef = {
+export interface CategoryRef {
     id: string;
     name: string;
-};
+}
 export type CategoryKind = OpenEnum<"category">;
 /** How a query matched source category names or exact paths through the lexical matcher. */
-export type CategoryMatch = {
+export interface CategoryMatch {
     /** The name or source path that matched. */
     matchedText: string | null;
     method: OpenEnum<"exact" | "alias" | "fuzzy">;
-};
+}
 /**
  * One item on a `categories.list` page: what picks the next call. `get(id)`
  * has the source path, depth, ancestors and children.
  */
-export type CategoryItem = {
+export interface CategoryItem {
     /** Whether `categories.list({ parentId: this.id })` lists anything. */
     hasChildren: boolean;
     /** A source category identity, also used in product_category memberships. */
@@ -39,14 +39,14 @@ export type CategoryItem = {
     parentId: string | null;
     path: string;
     depth: number;
-};
-export type CategoriesPageInfo = {
+}
+export interface CategoriesPageInfo {
     /** Pass back as `cursor` with the same `query` and `parentId` for the next page. */
     nextCursor: string | null;
     returnedCount: number;
     totalMatches: number;
-};
-export type CategoriesListInput = {
+}
+export interface CategoriesListInput {
     /** `pageInfo.nextCursor` from the previous page, with the same `query` and `parentId`. */
     cursor?: string;
     /** Items per page, 1 to 50. Default 20. */
@@ -55,21 +55,21 @@ export type CategoriesListInput = {
     parentId?: string;
     /** A category name or description, e.g. `"wallpaper"` or `"beds"`. */
     query?: string;
-};
-export type CategoriesListResult = {
+}
+export interface CategoriesListResult {
     items: CategoryItem[];
     /** Present only when the query is refused as a category, and says why. */
     notice?: string;
     pageInfo: CategoriesPageInfo;
-};
+}
 /** Independent semantic mapping metadata; it does not assert source category membership. */
-export type CategoryConcept = {
+export interface CategoryConcept {
     label: string;
     match?: OpenEnum<"exact" | "close" | "broad" | "narrow">;
     termId: string;
     uri: string;
-};
-export type CategoryProductCategory = {
+}
+export interface CategoryProductCategory {
     concepts: CategoryConcept[];
     /** Legacy semantic mapping value, separate from source product_category enum[] values. */
     recordValue: string | null;
@@ -79,8 +79,8 @@ export type CategoryProductCategory = {
      * fits yet.
      */
     status: OpenEnum<"mapped" | "conditional" | "unmapped">;
-};
-export type CategoriesGetResult = {
+}
+export interface CategoriesGetResult {
     /** Phrases that name this category in a `query`. */
     aliases: string[];
     /** The categories above this one, root first. Empty for a top-level category. */
@@ -98,4 +98,4 @@ export type CategoriesGetResult = {
     path: string;
     /** Zero-based depth in the source hierarchy. */
     depth: number;
-};
+}

package/client-config.d.ts

@@ -5,7 +5,7 @@
  */
 /** The hosted API origin the client talks to unless `baseUrl` overrides it. */
 export declare const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
-export type MaterialGraphClientOptions = {
+export interface MaterialGraphClientOptions {
     /** A `mg_read_*` API key, presented as `Authorization: Bearer <key>`. */
     apiKey: string;
     /** Override the API origin. Defaults to {@link DEFAULT_BASE_URL}. */
@@ -19,4 +19,4 @@ export type MaterialGraphClientOptions = {
      * they end or the caller aborts. Absent means no deadline.
      */
     timeoutMs?: number;
-};
+}

package/client-response-schema.d.ts

@@ -1,3 +1,3 @@
-import type { JsonSchema } from "./response-schemas.js";
+import type { JsonObject } from "./json.js";
 /** Adapt a fresh producer schema to the SDK's existing open string enums. */
-export declare const openClientResponseEnums: (schema: JsonSchema) => void;
+export declare const openClientResponseEnums: (schema: JsonObject) => void;

package/client-response-schema.js

@@ -1,4 +1,4 @@
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+import { isJsonObject } from "./json.js";
 // Only the fields declared as OpenEnum in the SDK are open here. Union
 // discriminants stay closed so their associated object shapes remain true.
 const openStrings = new Set([
@@ -47,19 +47,19 @@ const openStrings = new Set([
 /** Adapt a fresh producer schema to the SDK's existing open string enums. */
 export const openClientResponseEnums = (schema) => {
     const visit = (node, path) => {
-        if (!isRecord(node)) {
+        if (!isJsonObject(node)) {
             return;
         }
         if (node.type === "string" && openStrings.has(path)) {
             delete node.enum;
             delete node.const;
         }
-        if (isRecord(node.$defs)) {
+        if (isJsonObject(node.$defs)) {
             for (const [name, definition] of Object.entries(node.$defs)) {
                 visit(definition, name);
             }
         }
-        if (isRecord(node.properties)) {
+        if (isJsonObject(node.properties)) {
             for (const [name, property] of Object.entries(node.properties)) {
                 visit(property, `${path}.${name}`);
             }

package/client-vocabulary.js

@@ -1,6 +1,6 @@
 import { resolveOperation } from "./operations.js";
 export const resolveColor = async (transport, name, signal, options) => await transport.requestJson(resolveOperation("resolve_color_name"), {
-    query: { searchCatalogSubset: options?.searchCatalogSubset, name },
+    query: { name, searchCatalogSubset: options?.searchCatalogSubset },
     signal,
 });
 /**

package/client.d.ts

@@ -177,7 +177,7 @@ export declare class MaterialGraphClient {
      * materials catalog, never silently dropped from the page.
      *
      * `filters`/`optionalFilters`/`orderBy`/`colors` are sent as URL-encoded
-     * JSON; `attributes`/`include`/`words` as comma-separated lists — the server
+     * JSON; `attributes`/`observations`/`include`/`words` as comma-separated lists — the server
      * validates, this method does not duplicate that check.
      */
     listVariants(input: ListVariantsInput, signal?: AbortSignal): Promise<ListVariantsOutput>;

package/client.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;
@@ -182,6 +180,9 @@ export class MaterialGraphClient {
                 ? options.blocks.join(",")
                 : undefined,
             ifc: options?.ifc === true ? "true" : undefined,
+            observations: options?.observations !== undefined && options.observations.length > 0
+                ? options.observations.join(",")
+                : undefined,
         }, signal, { variantId });
     }
     async materialBlocks(variantId, signal) {
@@ -249,7 +250,7 @@ export class MaterialGraphClient {
      * materials catalog, never silently dropped from the page.
      *
      * `filters`/`optionalFilters`/`orderBy`/`colors` are sent as URL-encoded
-     * JSON; `attributes`/`include`/`words` as comma-separated lists — the server
+     * JSON; `attributes`/`observations`/`include`/`words` as comma-separated lists — the server
      * validates, this method does not duplicate that check.
      */
     async listVariants(input, signal) {
@@ -261,7 +262,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
@@ -269,12 +269,16 @@ export class MaterialGraphClient {
                 : undefined,
             limit: input.limit,
             name: input.name,
+            observations: input.observations !== undefined && input.observations.length > 0
+                ? input.observations.join(",")
+                : undefined,
             optionalFilters: input.optionalFilters
                 ? JSON.stringify(input.optionalFilters)
                 : undefined,
             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,11 +361,11 @@ export class MaterialGraphClient {
      */
     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);
     }
     /**

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;