@instruments/materialgraph 0.1.0

package/errors.js

@@ -0,0 +1,217 @@
+/** Error and rate-limit contracts for the retry-free MaterialGraph SDK. */
+const RETRIABLE_STATUS = new Set([502, 503, 504]);
+const MAX_UNEXPECTED_TEXT = 768;
+const MAX_EXTENSION_DEPTH = 8;
+const MAX_EXTENSION_ITEMS = 100;
+const MAX_EXTENSION_STRING = 1_024;
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function redact(text, secrets) {
+    return secrets.reduce((sanitized, secret) => {
+        if (secret.length === 0)
+            return sanitized;
+        return sanitized.split(secret).join("[REDACTED]");
+    }, text);
+}
+function safeString(text, secrets) {
+    return redact(text, secrets).slice(0, MAX_EXTENSION_STRING);
+}
+function secretVariants(apiKey, queryValues) {
+    return [
+        apiKey,
+        ...queryValues,
+        ...queryValues.map(encodeURIComponent),
+        ...queryValues.map((value) => new URLSearchParams([["value", value]]).toString().slice("value=".length)),
+    ];
+}
+function requestMetadata(input) {
+    return { method: input.method, origin: input.origin, path: input.path };
+}
+function 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);
+}
+function sanitizeRecord(value, secrets, depth) {
+    const entries = Object.entries(value)
+        .slice(0, MAX_EXTENSION_ITEMS)
+        .flatMap(([key, item]) => {
+        const sanitized = sanitizeValue(item, secrets, depth + 1);
+        return sanitized === undefined ? [] : [[safeString(key, secrets), sanitized]];
+    });
+    return Object.fromEntries(entries);
+}
+function sanitizeIssues(value, secrets) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .slice(0, MAX_EXTENSION_ITEMS)
+        .filter((issue) => isRecord(issue) && !Array.isArray(issue))
+        .map((issue) => sanitizeRecord(issue, secrets, 0));
+}
+function sanitizeSuggestions(value, secrets) {
+    if (!Array.isArray(value) || value.some((suggestion) => typeof suggestion !== "string")) {
+        return undefined;
+    }
+    return value.slice(0, MAX_EXTENSION_ITEMS).map((suggestion) => safeString(suggestion, secrets));
+}
+function 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")) {
+        return undefined;
+    }
+    const suggestions = sanitizeSuggestions(body.suggestions, secrets);
+    const issues = sanitizeIssues(body.issues, secrets);
+    return {
+        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 }),
+    };
+}
+function normalizeSimple(body, secrets) {
+    if (!isRecord(body) || typeof body.error !== "string")
+        return undefined;
+    const issues = sanitizeIssues(body.issues, secrets);
+    return {
+        error: safeString(body.error, secrets),
+        ...(issues === undefined ? {} : { issues }),
+    };
+}
+function unexpectedMessage(status, responseText, secrets) {
+    const sanitized = redact(responseText, secrets).trim().slice(0, MAX_UNEXPECTED_TEXT);
+    return sanitized.length > 0
+        ? `MaterialGraph request failed with HTTP ${status}: ${sanitized}`
+        : `MaterialGraph request failed with HTTP ${status}`;
+}
+/** The one error class thrown by all SDK transport and HTTP failures. */
+export class MaterialGraphError extends Error {
+    kind;
+    status;
+    retriable;
+    traceId;
+    problem;
+    simple;
+    rateLimit;
+    method;
+    origin;
+    path;
+    constructor(message, init) {
+        super(message);
+        this.name = "MaterialGraphError";
+        this.kind = init.kind;
+        this.status = init.status;
+        this.retriable = init.retriable;
+        this.traceId = init.traceId;
+        this.problem = init.problem;
+        this.simple = init.simple;
+        this.rateLimit = init.rateLimit ?? null;
+        this.method = init.method;
+        this.origin = init.origin;
+        this.path = init.path;
+    }
+    /** Compatibility alias for the former SDK property. */
+    get isRetriable() {
+        return this.retriable;
+    }
+    static unexpected(message) {
+        return new MaterialGraphError(message, { kind: "unexpected", retriable: false });
+    }
+    static fromTransport(input) {
+        if (input.callerSignal?.aborted === true) {
+            return new MaterialGraphError("MaterialGraph request aborted by caller", {
+                ...requestMetadata(input),
+                kind: "aborted",
+                retriable: false,
+            });
+        }
+        const name = input.cause instanceof Error ? input.cause.name : "";
+        if (name === "TimeoutError") {
+            return new MaterialGraphError("MaterialGraph request timed out", {
+                ...requestMetadata(input),
+                kind: "timeout",
+                retriable: false,
+            });
+        }
+        return new MaterialGraphError("MaterialGraph network request failed", {
+            ...requestMetadata(input),
+            kind: "network",
+            retriable: true,
+        });
+    }
+    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 retriable = RETRIABLE_STATUS.has(input.status);
+        const metadata = requestMetadata(input);
+        if (input.status === 429) {
+            return new MaterialGraphError(problem?.detail ?? simple?.error ?? "MaterialGraph rate limit exceeded (429)", {
+                ...metadata,
+                status: input.status,
+                rateLimit: input.rateLimit,
+                kind: "rate_limited",
+                retriable: false,
+                traceId: problem?.trace_id,
+                problem,
+                simple,
+            });
+        }
+        if (problem !== undefined) {
+            return new MaterialGraphError(problem.detail || problem.title, {
+                ...metadata,
+                status: input.status,
+                rateLimit: input.rateLimit,
+                kind: "problem",
+                retriable: retriable || problem.is_retriable,
+                traceId: problem.trace_id,
+                problem,
+            });
+        }
+        if (simple !== undefined) {
+            return new MaterialGraphError(simple.error, {
+                ...metadata,
+                status: input.status,
+                rateLimit: input.rateLimit,
+                kind: "simple",
+                retriable,
+                simple,
+            });
+        }
+        return new MaterialGraphError(unexpectedMessage(input.status, input.responseText, secrets), {
+            ...metadata,
+            kind: "unexpected",
+            status: input.status,
+            retriable,
+            rateLimit: input.rateLimit,
+        });
+    }
+}

package/index.d.ts

@@ -0,0 +1,12 @@
+export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.js";
+export type { MaterialGraphClientOptions, BrowseNamespace } from "./client.js";
+export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
+export type { SdkOperation, SdkOperationId } from "./operations.js";
+export { MaterialGraphError } from "./errors.js";
+export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
+export type * from "./types.js";
+export type * from "./brand-types.js";
+export type * from "./material-asset-types.js";
+export type * from "./material-block-types.js";
+export type * from "./schema-resource-types.js";
+export type * from "./search-refinement-types.js";

package/index.js

@@ -0,0 +1,3 @@
+export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.js";
+export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
+export { MaterialGraphError } from "./errors.js";

package/material-asset-types.d.ts

@@ -0,0 +1,35 @@
+import type { OpenEnum } from "./types.js";
+export type MaterialAssetVisualRole = OpenEnum<"grid" | "detail" | "scene" | "swatch" | "technical" | "unknown">;
+export type MaterialAssetStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "failed">;
+export interface MaterialAssetProjectionImage {
+    key: string;
+    ordinal: number;
+    proxyPath: string;
+    visualRole: MaterialAssetVisualRole;
+    status: MaterialAssetStatus;
+    contentType: string | null;
+    fileExtension: string | null;
+    filename: string | null;
+    byteSize: number | null;
+}
+export interface MaterialAssetProjectionDownload {
+    ordinal: number;
+    url: string;
+    label: string | null;
+    assetKind: string;
+    status: string;
+    contentType: string | null;
+    fileExtension: string | null;
+    filename: string | null;
+}
+export interface MaterialAssetProjectionSummary {
+    imageCount: number;
+    downloadCount: number;
+    downloadedImageCount: number;
+}
+export interface MaterialAssetProjection {
+    variantId: string;
+    images: MaterialAssetProjectionImage[];
+    downloads: MaterialAssetProjectionDownload[];
+    summary: MaterialAssetProjectionSummary;
+}

package/material-asset-types.js

@@ -0,0 +1 @@
+export {};

package/material-block-types.d.ts

@@ -0,0 +1,22 @@
+import type { OpenEnum } from "./types.js";
+export type MaterialBlockStatus = OpenEnum<"populated" | "partial" | "pending" | "not_applicable">;
+export type MaterialBlockFieldStatus = OpenEnum<"verified" | "partial" | "missing" | "not_applicable">;
+export type MaterialBlockFieldValue = string | number | boolean | unknown[] | Record<string, unknown> | null;
+export interface MaterialBlockProjectionField {
+    attributeId: string;
+    label: string;
+    value: MaterialBlockFieldValue;
+    unit?: string;
+    status: MaterialBlockFieldStatus;
+}
+export interface MaterialBlockProjectionItem {
+    canonicalBlockId: string;
+    canonicalBlockName: string;
+    status: MaterialBlockStatus;
+    fields: MaterialBlockProjectionField[];
+    missingAttributeIds: string[];
+}
+export interface MaterialBlockProjection {
+    variantId: string;
+    blocks: MaterialBlockProjectionItem[];
+}

package/material-block-types.js

@@ -0,0 +1 @@
+export {};

package/operations.d.ts

@@ -0,0 +1,11 @@
+export declare const MATERIALGRAPH_API_VERSION = "0.6.0";
+declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{slug}", "get_brand_profile"]];
+export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
+export type SdkOperation = Readonly<{
+    clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];
+    method: (typeof OPERATION_DEFINITIONS)[number][1];
+    path: (typeof OPERATION_DEFINITIONS)[number][2];
+    operationId: SdkOperationId;
+}>;
+export declare const SDK_OPERATIONS: readonly SdkOperation[];
+export {};

package/operations.js

@@ -0,0 +1,53 @@
+export const MATERIALGRAPH_API_VERSION = "0.6.0";
+const OPERATION_DEFINITIONS = [
+    ["search", "POST", "/api/v1/search", "search_materials_post"],
+    ["searchGet", "GET", "/api/v1/search", "search_materials_get"],
+    ["match", "POST", "/api/v1/search/match", "match_material"],
+    ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"],
+    ["material", "GET", "/api/v1/materials/{variantId}", "get_material"],
+    ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"],
+    ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"],
+    ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"],
+    ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"],
+    ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"],
+    ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"],
+    ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"],
+    ["schema", "GET", "/api/v1/schema/units", "list_schema_units"],
+    ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"],
+    ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"],
+    ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"],
+    ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"],
+    ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"],
+    ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"],
+    ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"],
+    ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"],
+    ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"],
+    ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"],
+    ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"],
+    ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"],
+    [
+        "resolveAttributeValue",
+        "GET",
+        "/api/v1/catalog/attributes/{attributeId}/values/resolve",
+        "catalog_resolve_value",
+    ],
+    ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"],
+    ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"],
+    ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"],
+    ["whoami", "GET", "/api/v1/whoami", "whoami"],
+    ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"],
+    ["demand", "GET", "/api/v1/demand", "get_material_demand"],
+    ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"],
+    ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"],
+    [
+        "attributeValues",
+        "GET",
+        "/api/v1/catalog/attributes/{attributeId}/values",
+        "list_attribute_values",
+    ],
+    ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"],
+    ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"],
+    ["brands", "GET", "/api/v1/brands", "list_brands"],
+    ["brand", "GET", "/api/v1/brands/{slug}", "get_brand_profile"],
+];
+export const SDK_OPERATIONS = Object.freeze(OPERATION_DEFINITIONS.map(([clientMethod, method, path, operationId]) => Object.freeze({ clientMethod, method, path, operationId })));

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@instruments/materialgraph",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "license": "Proprietary",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/materialinstruments/materialgraph.git",
+    "directory": "packages/sdk"
+  }
+}

package/schema-resource-types.d.ts

@@ -0,0 +1,163 @@
+import type { OpenEnum } from "./types.js";
+export type SchemaResource = "blocks" | "attributes" | "verticals" | "productTypes" | "units" | "valueDictionaries" | "sourceRequirements" | "productTypeTemplates" | "mappings";
+export type SchemaResourceRequest = SchemaResource;
+export interface SchemaLifecycle {
+    status: OpenEnum<"draft" | "active" | "deprecated">;
+    introducedIn: string;
+    deprecatedIn?: string;
+    supersededBy?: string;
+}
+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">;
+    notes?: string;
+}
+export interface SchemaBlockItem {
+    id: string;
+    semanticId: string;
+    lifecycle: SchemaLifecycle;
+    name: string;
+    description: string;
+    attributeIds: string[];
+}
+export type KnownSchemaQuantityKind = "length" | "area" | "volume" | "mass" | "time" | "temperature" | "currency" | "ratio" | "density" | "coverage" | "emissions" | "force" | "power" | "voltage" | "current" | "frequency" | "luminous_flux" | "color_temperature" | "count" | "unitless";
+export type SchemaQuantityKind = OpenEnum<KnownSchemaQuantityKind>;
+export interface SchemaAttributeItem {
+    id: string;
+    semanticId: string;
+    lifecycle: SchemaLifecycle;
+    name: string;
+    description: string;
+    valueKind: OpenEnum<"string" | "text" | "integer" | "number" | "boolean" | "enum" | "object" | "reference">;
+    quantityKind: SchemaQuantityKind | null;
+    canonicalUnitId: string | null;
+    acceptedUnitIds: string[];
+    valueDictionaryId: string | null;
+    defaultSourceRequirementId: string | null;
+    externalMappings: SchemaExternalMapping[];
+    searchFacet: boolean;
+    comparable: boolean;
+    usedInBlocks: string[];
+    enumValues: string[] | null;
+}
+export interface SchemaVerticalItem {
+    id: string;
+    displayName: string;
+    description: string;
+}
+export type SchemaApplicability = OpenEnum<"required" | "recommended" | "optional" | "unusual">;
+export interface SchemaProductTypeBlock {
+    blockId: string;
+    applicability: SchemaApplicability;
+    requiredAttributes?: string[];
+    optionalAttributes?: string[];
+    sourceRequirementId?: string;
+    completenessWeight?: number;
+    notes?: string;
+    optional?: boolean;
+}
+export interface SchemaProductTypeItem {
+    id: string;
+    name: string;
+    description?: string;
+    verticalId: string;
+    parentProductTypeGroupId?: string;
+    blocks: SchemaProductTypeBlock[];
+    productTypeSpecificAttributes?: string[];
+    semanticId: string;
+    lifecycle: SchemaLifecycle;
+}
+export interface SchemaUnitItem {
+    id: string;
+    name: string;
+    symbol: string;
+    quantityKind: SchemaQuantityKind;
+    acceptedSourceUnits?: string[];
+    conversionToCanonical?: {
+        factor: number;
+        offset?: number;
+    };
+    notes?: string;
+    semanticId: string;
+    lifecycle: SchemaLifecycle;
+}
+export interface SchemaValueDictionaryTerm {
+    id: string;
+    label: string;
+    aliases?: string[];
+    broaderTermId?: string;
+    externalMappings?: SchemaExternalMapping[];
+    semanticId: string;
+    lifecycle: SchemaLifecycle;
+}
+export interface SchemaValueDictionaryItem {
+    id: string;
+    name: string;
+    description: string;
+    terms: SchemaValueDictionaryTerm[];
+    semanticId: string;
+    lifecycle: SchemaLifecycle;
+}
+export type KnownSchemaSourceType = "manufacturer_page" | "technical_data_sheet" | "safety_data_sheet" | "test_report" | "certificate" | "image" | "commerce_page" | "catalog_pdf" | "derived_analysis";
+export type SchemaSourceType = OpenEnum<KnownSchemaSourceType>;
+export type KnownSchemaSourceMethod = "manual_review" | "agent_extract" | "pdf_extract" | "image_analysis" | "html_scrape" | "structured_feed" | "calculation";
+export type SchemaSourceMethod = OpenEnum<KnownSchemaSourceMethod>;
+export interface SchemaSourceRequirementItem {
+    id: string;
+    name: string;
+    description: string;
+    allowedSourceTypes: SchemaSourceType[];
+    allowedMethods: SchemaSourceMethod[];
+    minConfidence: number;
+    reviewRequired: boolean;
+    freshnessDays?: number;
+    sourceBasis?: OpenEnum<"declared" | "derived" | "tested">;
+    semanticId: string;
+    lifecycle: SchemaLifecycle;
+}
+export interface SchemaProductTypeTemplateBlock {
+    blockId: string;
+    applicability: SchemaApplicability;
+    requiredAttributes?: string[];
+    optionalAttributes?: string[];
+    sourceRequirementId?: string;
+    completenessWeight?: number;
+    notes?: string;
+}
+export interface SchemaProductTypeTemplateItem {
+    id: string;
+    name: string;
+    productTypeId: string;
+    blocks: SchemaProductTypeTemplateBlock[];
+    defaultSourceRequirementId?: string;
+    notes?: string;
+    semanticId: string;
+    lifecycle: SchemaLifecycle;
+}
+export interface SchemaMappingItem {
+    target: SchemaExternalMapping["target"];
+    subjectKind?: OpenEnum<"attribute" | "block" | "product_type" | "template" | "unit" | "value_dictionary" | "value_dictionary_term">;
+    subjectId?: string;
+    canonicalPath: string;
+    targetPath: string;
+    mappingType: SchemaExternalMapping["mappingType"];
+    notes?: string;
+}
+export interface SchemaResourceItemMap {
+    blocks: SchemaBlockItem;
+    attributes: SchemaAttributeItem;
+    verticals: SchemaVerticalItem;
+    productTypes: SchemaProductTypeItem;
+    units: SchemaUnitItem;
+    valueDictionaries: SchemaValueDictionaryItem;
+    sourceRequirements: SchemaSourceRequirementItem;
+    productTypeTemplates: SchemaProductTypeTemplateItem;
+    mappings: SchemaMappingItem;
+}
+export interface SchemaResourceResponse<K extends SchemaResource = SchemaResource> {
+    kind: K;
+    schemaVersion: string;
+    items: SchemaResourceItemMap[K][];
+    totalCount: number;
+}

package/schema-resource-types.js

@@ -0,0 +1 @@
+export {};

package/search-refinement-types.d.ts

@@ -0,0 +1,16 @@
+/** Types for structured refinements returned by MaterialGraph search. */
+import type { SearchInput } from "./types.js";
+/** A hard canonical-attribute filter accepted by the search engine. */
+export type SearchFilter = {
+    attributeId: string;
+    term: string;
+} | {
+    attributeId: string;
+    hasValue: true;
+};
+/** One structured refinement returned with a search response. */
+export interface SearchSuggestion {
+    label: string;
+    /** Complete replacement request, not a partial patch. */
+    request: SearchInput;
+}

package/search-refinement-types.js

@@ -0,0 +1 @@
+export {};