@instruments/materialgraph 0.1.0

package/brand-types.d.ts

@@ -0,0 +1,25 @@
+/** Query options and wire types for the canonical brands collection. */
+export interface BrandsOptions {
+    q?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface BrandCatalogListItem {
+    id: string;
+    slug: string;
+    name: string;
+    primaryMarketSegment: string;
+    homepageUrl: string | null;
+    productCount: number;
+    variantCount: number;
+}
+export interface BrandCatalogListPage {
+    items: BrandCatalogListItem[];
+    meta: {
+        count: number;
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}

package/brand-types.js

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

package/catalog-discovery-types.d.ts

@@ -0,0 +1,47 @@
+/** Catalog value-discovery contracts mirrored from the canonical HTTP routes. */
+import type { OpenEnum } from "./types.js";
+/** Options for resolving a free-text value against one attribute's dictionary. */
+export interface ResolveAttributeValueOptions {
+    limit?: number;
+}
+/** One ranked canonical value candidate. */
+export interface ResolveValueCandidate {
+    id: string;
+    label: string;
+    dictionaryId?: string;
+    score: number;
+    tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
+    /** Present only for a colour_family candidate resolved via the colorscope fallback. */
+    via?: OpenEnum<"colorscope">;
+}
+/** Response from resolving a free-text value against one attribute's dictionary. */
+export interface ResolveAttributeValueResponse {
+    attribute: {
+        id: string;
+        name: string;
+        dictionaryId: string;
+    };
+    resolution: {
+        status: OpenEnum<"resolved" | "ambiguous" | "unresolved">;
+        query: string;
+        best: ResolveValueCandidate | null;
+        candidates: ResolveValueCandidate[];
+        recommendedAction: OpenEnum<"use_best" | "choose_from_candidates" | "ask_user" | "none_found">;
+    };
+}
+/** Options for searching registry attributes and value-dictionary terms together. */
+export interface VocabularySearchOptions {
+    limit?: number;
+    kind?: "attribute" | "term";
+}
+/** One ranked cross-vocabulary candidate. */
+export interface VocabularySearchCandidate extends ResolveValueCandidate {
+    kind: OpenEnum<"attribute" | "term">;
+    /** Present for terms: attributes whose value dictionary owns this term. */
+    attributeIds?: string[];
+}
+/** Response from the cross-vocabulary catalog search. */
+export interface VocabularySearchResponse {
+    query: string;
+    results: VocabularySearchCandidate[];
+}

package/catalog-discovery-types.js

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

package/client.d.ts

@@ -0,0 +1,119 @@
+import { type RateLimit } from "./errors.js";
+import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
+import type { MaterialAssetProjection } from "./material-asset-types.js";
+import type { MaterialBlockProjection } from "./material-block-types.js";
+import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
+import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, ByColourParams, ByColourResponse, BrowseParams, BrowseResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, MatchInput, MatchResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, TaxonomyResponse, VocabularySearchOptions, VocabularySearchResponse, WhoamiResponse } from "./types.js";
+export declare const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
+export declare const MAX_BATCH_IDS = 100;
+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}. */
+    baseUrl?: string;
+    /** Inject a custom `fetch` (tests, proxies). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+export interface BrowseNamespace {
+    (params: BrowseParams, signal?: AbortSignal): Promise<BrowseResponse>;
+    pages(params: BrowseParams, signal?: AbortSignal): AsyncGenerator<BrowseResponse, void, unknown>;
+}
+export declare class MaterialGraphClient {
+    #private;
+    readonly baseUrl: string;
+    readonly browse: BrowseNamespace;
+    constructor(options: MaterialGraphClientOptions);
+    get lastRateLimit(): RateLimit | null;
+    search(input: SearchInput, signal?: AbortSignal): Promise<SearchResponse>;
+    searchGet(params: SearchGetParams, signal?: AbortSignal): Promise<SearchResponse>;
+    match(input: MatchInput, signal?: AbortSignal): Promise<MatchResponse>;
+    byColour(params: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
+    /** Get a single material's detail record (GET `/api/v1/materials/{variantId}`). */
+    material(variantId: string, options?: {
+        includeSiblings?: boolean;
+    }, signal?: AbortSignal): Promise<MaterialResponse>;
+    /** The other variants of the same product (GET `/api/v1/materials/{variantId}/siblings`). */
+    siblings(variantId: string, signal?: AbortSignal): Promise<SiblingsResponse>;
+    /** Canonical block completeness for a material (GET `/api/v1/materials/{variantId}/blocks`). */
+    materialBlocks(variantId: string, signal?: AbortSignal): Promise<MaterialBlockProjection>;
+    /** Safe images and downloads for a material (GET `/api/v1/materials/{variantId}/assets`). */
+    materialAssets(variantId: string, signal?: AbortSignal): Promise<MaterialAssetProjection>;
+    /** Read one static governed schema resource. */
+    schema<K extends SchemaResource>(resource: K, signal?: AbortSignal): Promise<SchemaResourceResponse<K>>;
+    /** The "what pairs with this material" rail (GET `/api/v1/materials/{variantId}/pairings`). */
+    pairings(variantId: string, options?: PairingsOptions, signal?: AbortSignal): Promise<PairingsResponse>;
+    /**
+     * Batch-read materials by id (POST `/api/v1/materials/batch`, ≤ 100 ids).
+     * Throws client-side before any request when more than {@link MAX_BATCH_IDS}
+     * ids are supplied.
+     */
+    materials(ids: string[], options: {
+        view: "detail";
+        idKind?: MaterialsBatchOptions["idKind"];
+    }, signal?: AbortSignal): Promise<MaterialsBatchDetailResponse>;
+    materials(ids: string[], options?: {
+        view?: "tile";
+        idKind?: MaterialsBatchOptions["idKind"];
+    }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
+    /**
+     * Cacheable GET form of the batch read (GET `/api/v1/materials/batch`,
+     * `Cache-Control: public, max-age=300`). Same response as {@link materials};
+     * prefer this for repeatable, cache-friendly id sets. Also ≤ 100 ids.
+     */
+    materialsCached(ids: string[], options: {
+        view: "detail";
+        idKind?: MaterialsBatchGetOptions["idKind"];
+    }, signal?: AbortSignal): Promise<MaterialsBatchDetailResponse>;
+    materialsCached(ids: string[], options?: {
+        view?: "tile";
+        idKind?: MaterialsBatchGetOptions["idKind"];
+    }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
+    /** The three canonical colour vocabularies with live counts (GET `/api/v1/colours/facets`). */
+    colourFacets(signal?: AbortSignal): Promise<ColourFacetsResponse>;
+    /** Resolve a colour name/phrase to a hex (GET `/api/v1/search/colours/resolve`). */
+    resolveColour(name: string, signal?: AbortSignal): Promise<ResolveColourResponse>;
+    /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
+    suggestColour(q: string, options?: {
+        limit?: number;
+    }, signal?: AbortSignal): Promise<SuggestColourResponse>;
+    /** Resolve a free-text spec phrase to canonical attribute ids (GET `/api/v1/catalog/attributes/resolve`). */
+    resolveAttribute(q: string, options?: ResolveAttributeOptions, signal?: AbortSignal): Promise<ResolveAttributeResponse>;
+    /** Resolve a value phrase against one canonical attribute's dictionary. */
+    resolveAttributeValue(attributeId: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal): Promise<ResolveAttributeValueResponse>;
+    /** Search canonical attributes and value-dictionary terms together. */
+    searchVocabulary(query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<VocabularySearchResponse>;
+    /**
+     * Find materials by canonical specification (GET `/api/v1/search/specifications`).
+     * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL.
+     */
+    bySpec(spec: string | string[], options?: BySpecOptions, signal?: AbortSignal): Promise<BySpecResponse>;
+    /** The product-category tree, flattened (GET `/api/v1/taxonomy/categories`). */
+    taxonomy(signal?: AbortSignal): Promise<TaxonomyResponse>;
+    /** Echo the authenticated principal and scopes (GET `/api/v1/whoami`). */
+    whoami(signal?: AbortSignal): Promise<WhoamiResponse>;
+    /**
+     * Coordinate a palette of already-chosen materials (POST
+     * `/api/v1/pairings/coordinate`). Returns demand-lift-ranked companions with
+     * colour swatches and an annotate-only `colourFit` (never reorders in v1).
+     */
+    coordinate(input: CoordinateInput, signal?: AbortSignal): Promise<CoordinateResponse>;
+    /**
+     * How much a material is specified, plus what's specified alongside it (GET
+     * `/api/v1/demand`). Provide EXACTLY ONE of `variantId` or `material`.
+     */
+    demand(params: DemandParams, signal?: AbortSignal): Promise<DemandResponse>;
+    /** Extract a named colour palette from an uploaded image (POST `/api/v1/search/palettes/extract`). */
+    extractPalette(input: ExtractPaletteInput, signal?: AbortSignal): Promise<ExtractPaletteResponse>;
+    /** Discover the live specification-facet collection. */
+    specificationFacets(signal?: AbortSignal): Promise<SpecFacetsListResponse>;
+    /** List the live values for one canonical attribute. */
+    attributeValues(attributeId: string, signal?: AbortSignal): Promise<SpecFacetsDistributionResponse>;
+    /** The specs a product type COULD carry (GET `/api/v1/taxonomy/categories/{key}/specs`). */
+    applicableSpecs(key: string, signal?: AbortSignal): Promise<ApplicableSpecsResponse>;
+    /** Resolve a term to its meaning in the schema (GET `/api/v1/glossary/{term}`). */
+    glossary(term: string, signal?: AbortSignal): Promise<GlossaryTermResponse>;
+    /** List registered brands (GET `/api/v1/brands`). */
+    brands(options?: BrandsOptions, signal?: AbortSignal): Promise<BrandCatalogListPage>;
+    /** Resolve a brand and return its profile + trade signals (GET `/api/v1/brands/{slug}`). */
+    brand(slug: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
+}

package/client.js

@@ -0,0 +1,333 @@
+import { MaterialGraphError } from "./errors.js";
+import { SDK_OPERATIONS } from "./operations.js";
+export const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
+export const MAX_BATCH_IDS = 100;
+const SCHEMA_RESOURCE_OPERATION_IDS = {
+    blocks: "list_schema_blocks",
+    attributes: "list_schema_attributes",
+    verticals: "list_schema_verticals",
+    productTypes: "list_schema_product_types",
+    units: "list_schema_units",
+    valueDictionaries: "list_schema_value_dictionaries",
+    sourceRequirements: "list_schema_source_requirements",
+    productTypeTemplates: "list_schema_product_type_templates",
+    mappings: "list_schema_mappings",
+};
+function operation(operationId) {
+    const match = SDK_OPERATIONS.find((candidate) => candidate.operationId === operationId);
+    if (!match) {
+        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
+    }
+    return match;
+}
+function operationPath(sdkOperation, pathParams = {}) {
+    return Object.entries(pathParams).reduce((path, [name, value]) => path.replace(`{${name}}`, encodeURIComponent(value)), sdkOperation.path);
+}
+function parseIntOrNull(value) {
+    if (value === null)
+        return null;
+    const n = Number.parseInt(value, 10);
+    return Number.isNaN(n) ? null : n;
+}
+function parseRateLimit(headers) {
+    const limit = parseIntOrNull(headers.get("x-ratelimit-limit"));
+    const remaining = parseIntOrNull(headers.get("x-ratelimit-remaining"));
+    const reset = parseIntOrNull(headers.get("x-ratelimit-reset"));
+    const retryAfter = parseIntOrNull(headers.get("retry-after"));
+    if (limit === null && remaining === null && reset === null && retryAfter === null) {
+        return null;
+    }
+    return { limit, remaining, reset, retryAfter };
+}
+export class MaterialGraphClient {
+    baseUrl;
+    browse;
+    #apiKey;
+    #fetch;
+    #lastRateLimit = null;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw MaterialGraphError.unexpected("MaterialGraphClient: `apiKey` is required.");
+        }
+        this.#apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.#fetch = options.fetch ?? globalThis.fetch;
+        const browse = (params, signal) => this.#browsePage(params, signal);
+        browse.pages = (params, signal) => this.#browsePages(params, signal);
+        this.browse = browse;
+    }
+    get lastRateLimit() {
+        return this.#lastRateLimit;
+    }
+    #buildUrl(path, query) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value === undefined || value === null)
+                    continue;
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        if (item !== undefined && item !== null) {
+                            url.searchParams.append(key, String(item));
+                        }
+                    }
+                }
+                else {
+                    url.searchParams.append(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+    async #request(sdkOperation, options = {}) {
+        const path = operationPath(sdkOperation, options.pathParams);
+        const url = this.#buildUrl(path, options.query);
+        const requestUrl = new URL(url);
+        const requestMetadata = {
+            method: sdkOperation.method,
+            origin: requestUrl.origin,
+            path: requestUrl.pathname,
+        };
+        const headers = {
+            Authorization: `Bearer ${this.#apiKey}`,
+            Accept: "application/json",
+        };
+        const hasBody = options.body !== undefined;
+        if (hasBody)
+            headers["Content-Type"] = "application/json";
+        let response;
+        try {
+            response = await this.#fetch(url, {
+                method: sdkOperation.method,
+                headers,
+                body: hasBody ? JSON.stringify(options.body) : undefined,
+                signal: options.signal,
+            });
+        }
+        catch (cause) {
+            throw MaterialGraphError.fromTransport({
+                ...requestMetadata,
+                cause,
+                callerSignal: options.signal,
+            });
+        }
+        const rateLimit = parseRateLimit(response.headers);
+        this.#lastRateLimit = rateLimit;
+        let text;
+        try {
+            text = await response.text();
+        }
+        catch (cause) {
+            throw MaterialGraphError.fromTransport({
+                ...requestMetadata,
+                cause,
+                callerSignal: options.signal,
+            });
+        }
+        let parsed;
+        if (text.length > 0) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!response.ok) {
+            const querySecrets = [...requestUrl.searchParams.values()];
+            throw MaterialGraphError.fromResponse({
+                ...requestMetadata,
+                status: response.status,
+                body: parsed,
+                responseText: text,
+                rateLimit,
+                apiKey: this.#apiKey,
+                queryValues: querySecrets,
+            });
+        }
+        return parsed;
+    }
+    #get(operationId, query, signal, pathParams) {
+        return this.#request(operation(operationId), { query, signal, pathParams });
+    }
+    #post(operationId, body, signal) {
+        return this.#request(operation(operationId), { body, signal });
+    }
+    search(input, signal) {
+        return this.#post("search_materials_post", input, signal);
+    }
+    searchGet(params, signal) {
+        return this.#get("search_materials_get", { ...params }, signal);
+    }
+    match(input, signal) {
+        return this.#post("match_material", input, signal);
+    }
+    byColour(params, signal) {
+        return this.#get("search_by_colour", {
+            hex: params.hex,
+            colour: params.colour,
+            l: params.l,
+            a: params.a,
+            b: params.b,
+            category: params.category,
+            limit: params.limit,
+        }, signal);
+    }
+    // ── Materials ──────────────────────────────────────────────────────────────
+    /** Get a single material's detail record (GET `/api/v1/materials/{variantId}`). */
+    material(variantId, options, signal) {
+        return this.#get("get_material", options?.includeSiblings ? { include: "siblings" } : undefined, signal, { variantId });
+    }
+    /** The other variants of the same product (GET `/api/v1/materials/{variantId}/siblings`). */
+    siblings(variantId, signal) {
+        return this.#get("get_material_siblings", undefined, signal, { variantId });
+    }
+    /** Canonical block completeness for a material (GET `/api/v1/materials/{variantId}/blocks`). */
+    materialBlocks(variantId, signal) {
+        return this.#get("list_material_blocks", undefined, signal, {
+            variantId,
+        });
+    }
+    /** Safe images and downloads for a material (GET `/api/v1/materials/{variantId}/assets`). */
+    materialAssets(variantId, signal) {
+        return this.#get("list_material_assets", undefined, signal, {
+            variantId,
+        });
+    }
+    /** Read one static governed schema resource. */
+    schema(resource, signal) {
+        return this.#get(SCHEMA_RESOURCE_OPERATION_IDS[resource], undefined, signal);
+    }
+    /** The "what pairs with this material" rail (GET `/api/v1/materials/{variantId}/pairings`). */
+    pairings(variantId, options, signal) {
+        return this.#get("get_material_pairings", { categories: options?.categories, limit: options?.limit }, signal, { variantId });
+    }
+    materials(ids, options, signal) {
+        if (ids.length > MAX_BATCH_IDS) {
+            throw MaterialGraphError.unexpected(`MaterialGraphClient.materials(): at most ${MAX_BATCH_IDS} ids per call, received ${ids.length}. Split into multiple batches.`);
+        }
+        return this.#post("get_materials_batch_post", { ids, view: options?.view ?? "tile", idKind: options?.idKind ?? "variantId" }, signal);
+    }
+    materialsCached(ids, options, signal) {
+        if (ids.length > MAX_BATCH_IDS) {
+            throw MaterialGraphError.unexpected(`MaterialGraphClient.materialsCached(): at most ${MAX_BATCH_IDS} ids per call, received ${ids.length}. Split into multiple batches.`);
+        }
+        return this.#get("get_materials_batch_get", {
+            ids: ids.join(","),
+            view: options?.view ?? "tile",
+            idKind: options?.idKind ?? "variantId",
+        }, signal);
+    }
+    // ── Browse (private impls behind the `browse` namespace) ─────────────────────
+    #browsePage(params, signal) {
+        return this.#get("search_browse_by_colour", {
+            sort: params.sort,
+            cursor: params.cursor,
+            limit: params.limit,
+            types: params.types,
+        }, signal);
+    }
+    async *#browsePages(params, signal) {
+        let cursor = params.cursor;
+        for (;;) {
+            const page = await this.#browsePage({ ...params, cursor }, signal);
+            yield page;
+            if (page.cursor === undefined || page.results.length === 0)
+                return;
+            cursor = page.cursor;
+        }
+    }
+    // ── Colour helpers ───────────────────────────────────────────────────────────
+    /** The three canonical colour vocabularies with live counts (GET `/api/v1/colours/facets`). */
+    colourFacets(signal) {
+        return this.#get("get_colour_facets", undefined, signal);
+    }
+    /** Resolve a colour name/phrase to a hex (GET `/api/v1/search/colours/resolve`). */
+    resolveColour(name, signal) {
+        return this.#get("resolve_colour_name", { name }, signal);
+    }
+    /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
+    suggestColour(q, options, signal) {
+        return this.#get("suggest_colour_names", { q, limit: options?.limit }, signal);
+    }
+    // ── Catalog ──────────────────────────────────────────────────────────────────
+    /** Resolve a free-text spec phrase to canonical attribute ids (GET `/api/v1/catalog/attributes/resolve`). */
+    resolveAttribute(q, options, signal) {
+        return this.#get("catalog_resolve_attribute", { q, limit: options?.limit, facetableOnly: options?.facetableOnly }, signal);
+    }
+    /** Resolve a value phrase against one canonical attribute's dictionary. */
+    resolveAttributeValue(attributeId, query, options, signal) {
+        return this.#get("catalog_resolve_value", { q: query, limit: options?.limit }, signal, { attributeId });
+    }
+    /** Search canonical attributes and value-dictionary terms together. */
+    searchVocabulary(query, options, signal) {
+        return this.#get("catalog_vocabulary_search", { q: query, limit: options?.limit, kind: options?.kind }, signal);
+    }
+    /**
+     * Find materials by canonical specification (GET `/api/v1/search/specifications`).
+     * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL.
+     */
+    bySpec(spec, options, signal) {
+        return this.#get("catalog_by_spec", { spec: Array.isArray(spec) ? spec : [spec], limit: options?.limit }, signal);
+    }
+    // ── Taxonomy + meta ──────────────────────────────────────────────────────────
+    /** The product-category tree, flattened (GET `/api/v1/taxonomy/categories`). */
+    taxonomy(signal) {
+        return this.#get("get_category_taxonomy", undefined, signal);
+    }
+    /** Echo the authenticated principal and scopes (GET `/api/v1/whoami`). */
+    whoami(signal) {
+        return this.#get("whoami", undefined, signal);
+    }
+    // ── Pairings / demand ────────────────────────────────────────────────────────
+    /**
+     * Coordinate a palette of already-chosen materials (POST
+     * `/api/v1/pairings/coordinate`). Returns demand-lift-ranked companions with
+     * colour swatches and an annotate-only `colourFit` (never reorders in v1).
+     */
+    coordinate(input, signal) {
+        return this.#post("coordinate_materials", input, signal);
+    }
+    /**
+     * How much a material is specified, plus what's specified alongside it (GET
+     * `/api/v1/demand`). Provide EXACTLY ONE of `variantId` or `material`.
+     */
+    demand(params, signal) {
+        return this.#get("get_material_demand", { variantId: params.variantId, material: params.material }, signal);
+    }
+    // ── Colour helpers (extract) ─────────────────────────────────────────────────
+    /** Extract a named colour palette from an uploaded image (POST `/api/v1/search/palettes/extract`). */
+    extractPalette(input, signal) {
+        return this.#post("extract_image_palette", input, signal);
+    }
+    // ── Catalog (facets / applicable specs / glossary) ───────────────────────────
+    /** Discover the live specification-facet collection. */
+    specificationFacets(signal) {
+        return this.#get("list_spec_facets", undefined, signal);
+    }
+    /** List the live values for one canonical attribute. */
+    attributeValues(attributeId, signal) {
+        return this.#get("list_attribute_values", undefined, signal, {
+            attributeId,
+        });
+    }
+    /** The specs a product type COULD carry (GET `/api/v1/taxonomy/categories/{key}/specs`). */
+    applicableSpecs(key, signal) {
+        return this.#get("get_applicable_specs", undefined, signal, { key });
+    }
+    /** Resolve a term to its meaning in the schema (GET `/api/v1/glossary/{term}`). */
+    glossary(term, signal) {
+        return this.#get("explain_material_term", undefined, signal, { term });
+    }
+    // ── Brands ───────────────────────────────────────────────────────────────────
+    /** List registered brands (GET `/api/v1/brands`). */
+    brands(options = {}, signal) {
+        return this.#get("list_brands", { q: options.q, limit: options.limit, offset: options.offset }, signal);
+    }
+    /** Resolve a brand and return its profile + trade signals (GET `/api/v1/brands/{slug}`). */
+    brand(slug, options, signal) {
+        return this.#get("get_brand_profile", { q: options?.q }, signal, {
+            slug,
+        });
+    }
+}

package/errors.d.ts

@@ -0,0 +1,83 @@
+/** Error and rate-limit contracts for the retry-free MaterialGraph SDK. */
+export type MaterialGraphErrorKind = "problem" | "simple" | "network" | "timeout" | "aborted" | "rate_limited" | "unexpected";
+export type SanitizedErrorValue = null | boolean | number | string | SanitizedErrorValue[] | SanitizedIssue;
+/** A bounded, recursively sanitized validation-issue record. */
+export interface SanitizedIssue {
+    [key: string]: SanitizedErrorValue;
+}
+/** Normalized RFC 7807 body. Unknown response fields are intentionally discarded. */
+export interface ProblemDetail {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    instance?: string;
+    is_retriable: boolean;
+    trace_id: string;
+    suggestions?: string[];
+    doc_uri?: string;
+    issues?: SanitizedIssue[];
+}
+/** Normalized residual `{ error }` body. Unknown response fields are discarded. */
+export interface SimpleErrorBody {
+    error: string;
+    issues?: SanitizedIssue[];
+}
+/** Parsed `X-RateLimit-*` / `Retry-After` headers. `null` means absent. */
+export interface RateLimit {
+    limit: number | null;
+    remaining: number | null;
+    reset: number | null;
+    retryAfter: number | null;
+}
+export interface MaterialGraphRequestMetadata {
+    method: string;
+    origin: string;
+    path: string;
+}
+export interface MaterialGraphErrorInit {
+    kind: MaterialGraphErrorKind;
+    status?: number;
+    retriable: boolean;
+    traceId?: string;
+    problem?: ProblemDetail;
+    simple?: SimpleErrorBody;
+    rateLimit?: RateLimit | null;
+    method?: string;
+    origin?: string;
+    path?: string;
+    /** Accepted for compatibility but deliberately never retained on the public error. */
+    cause?: unknown;
+}
+interface ResponseErrorInput extends MaterialGraphRequestMetadata {
+    status: number;
+    body: unknown;
+    responseText: string;
+    rateLimit: RateLimit | null;
+    apiKey: string;
+    queryValues: readonly string[];
+}
+interface TransportErrorInput extends MaterialGraphRequestMetadata {
+    cause: unknown;
+    callerSignal?: AbortSignal;
+}
+/** The one error class thrown by all SDK transport and HTTP failures. */
+export declare class MaterialGraphError extends Error {
+    readonly kind: MaterialGraphErrorKind;
+    readonly status: number | undefined;
+    readonly retriable: boolean;
+    readonly traceId: string | undefined;
+    readonly problem: ProblemDetail | undefined;
+    readonly simple: SimpleErrorBody | undefined;
+    readonly rateLimit: RateLimit | null;
+    readonly method: string | undefined;
+    readonly origin: string | undefined;
+    readonly path: string | undefined;
+    constructor(message: string, init: MaterialGraphErrorInit);
+    /** Compatibility alias for the former SDK property. */
+    get isRetriable(): boolean;
+    static unexpected(message: string): MaterialGraphError;
+    static fromTransport(input: TransportErrorInput): MaterialGraphError;
+    static fromResponse(input: ResponseErrorInput): MaterialGraphError;
+}
+export {};