@instruments/materialgraph 0.1.0

package/types.d.ts

@@ -0,0 +1,749 @@
+/**
+ * Hand-mirrored wire types for the MaterialGraph public API (spec 0.5.0).
+ *
+ * These interfaces intentionally have NO runtime dependency on any
+ * `@materialgraph/*` package — they are a standalone, publishable mirror of the
+ * shapes in `apps/web/public/openapi.yaml` and the captured fixtures under
+ * `docs/surface/fixtures/v0.5.0/`. The `contract-parity` test re-checks them
+ * against the real Zod schemas so the mirror cannot silently drift.
+ * TOLERANT-PARSING CONTRACT: the public surface declares open response enums —
+ * "clients must tolerate unknown enum values and unknown fields". Every union
+ * that mirrors a server enum is therefore widened with `(string & {})` so a new
+ * server value still type-checks, and objects that may grow fields are read
+ * structurally (unknown keys pass through untouched — the client never strips).
+ */
+import type { SearchFilter, SearchSuggestion } from "./search-refinement-types.js";
+/** A widened string-literal union: known members autocomplete, unknown values still type-check. */
+export type OpenEnum<T extends string> = T | (string & {});
+/** One palette swatch of a material's main image. */
+export interface PaletteSwatch {
+    hex: string;
+    proportion: number;
+    /** Stored human colour name for the swatch, when one was extracted. */
+    name?: string | null;
+}
+/** Loose colour metadata for a search result's main image; every field is independently optional. */
+export interface ColourMeta {
+    mood?: string;
+    dominantFamily?: string;
+    dominantHex?: string;
+}
+/** OKLab triple. */
+export interface OklabTriple {
+    l: number;
+    a: number;
+    b: number;
+}
+/** The material's dominant-colour block (tile/detail projections). */
+export interface MaterialColour {
+    dominantHex: string | null;
+    hsl: {
+        h: number;
+        s: number;
+        l: number;
+    } | null;
+    oklab: OklabTriple | null;
+    chroma: number | null;
+    vibrancy: number | null;
+}
+/** Where the served image came from. */
+export type ImageSource = OpenEnum<"r2" | "origin">;
+/** The grid-card projection of a material. */
+export interface MaterialTile {
+    variantId: string;
+    brand: string;
+    product: string;
+    variantName: string | null;
+    imageUrl: string | null;
+    imageSource: ImageSource | null;
+    category: string | null;
+    colour: MaterialColour;
+}
+/** A canonical attribute/term pair carried on a detail record. */
+export interface MaterialFacet {
+    attributeId: string;
+    term: string;
+}
+/**
+ * One dimensional configuration of a material. Numeric fields are millimetres
+ * (mass in kilograms); string fields are the source's own descriptors. The
+ * index signature preserves the corpus's long tail of rarer keys.
+ */
+export interface DimensionEntry {
+    label?: string;
+    tile_size?: string;
+    measurement_basis?: string;
+    width_mm?: number;
+    length_mm?: number;
+    height_mm?: number;
+    depth_mm?: number;
+    thickness_mm?: number;
+    diameter_mm?: number;
+    visible_projection_mm?: number;
+    weight_kg?: number;
+    [key: string]: unknown;
+}
+/** The record projection of a material — the tile plus detail-only fields. */
+export interface MaterialDetail extends MaterialTile {
+    brandSlug: string;
+    productId: string;
+    color: string | null;
+    materialBankId: string | null;
+    installationImageUrl: string | null;
+    displayCategory: string | null;
+    categoryPath: string[];
+    palette: PaletteSwatch[];
+    facets: MaterialFacet[];
+    dimensions: DimensionEntry[] | null;
+}
+/** Per-signal scores, present on a result when `explain` was requested. */
+export interface SearchResultSignals {
+    image: number | null;
+    category: number | null;
+    colour: number | null;
+    lexical: number | null;
+}
+/** An accepted/measured visual meaning — descriptive evidence, never a ranking cause. */
+export interface VisualMeaning {
+    id: string;
+    label: string;
+    values: string[];
+    basis: OpenEnum<"canonical_attribute" | "image_colour_analysis">;
+    confidence?: number;
+    sourceBasis?: string;
+    version?: string;
+    appliedAt?: string;
+}
+/** One material in a search / match result list. */
+export interface SearchResultItem {
+    variantId: string;
+    brand: string;
+    product: string;
+    brandSlug: string | null;
+    productId: string | null;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    hasImage: boolean;
+    palette: PaletteSwatch[];
+    colourMeta?: ColourMeta;
+    /** Fused score — range [0, sum of active weights]; see `maxScore`. */
+    score: number;
+    signals?: SearchResultSignals;
+    retired?: boolean;
+    siblingCount?: number;
+    visualMeanings?: VisualMeaning[];
+}
+/** The single candidate source a query resolved to. */
+export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical">;
+/** Rerank-term report (absent in colour mode — there colour IS the source). */
+export interface SearchRerankReport {
+    colour?: OpenEnum<"ok" | "failed" | "skipped">;
+    colourWeight?: number;
+    colourLabel?: string;
+}
+/** The full search response (both GET and POST forms return this envelope). */
+export interface SearchResponse {
+    results: SearchResultItem[];
+    suggestions: SearchSuggestion[];
+    mode: SearchMode;
+    maxScore: number;
+    cursor?: string;
+    rerank?: SearchRerankReport;
+    variantCount?: number;
+    productCount?: number;
+    note?: string;
+    timings?: Record<string, number>;
+    /** Echo of the resolved query input (raw image bytes/vector are never echoed). */
+    query?: Record<string, unknown>;
+    /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
+    seed?: MaterialTile | Record<string, unknown>;
+}
+/** An inferred product-type category from the query image, with its boost. */
+export interface MatchCategoryInference {
+    productTypeId: string;
+    displayName: string;
+    boost: number;
+}
+/** The Material Match response (non-streaming form). */
+export interface MatchResponse {
+    results: SearchResultItem[];
+    inferredCategories: MatchCategoryInference[];
+    qualityFloor: number;
+    poolSize: number;
+    droppedBelowFloor: number;
+    droppedAsDuplicateProduct: number;
+    note?: string;
+}
+/** Coarse group + fine type of a colour match's primary product type. */
+export interface MatchCategory {
+    group: string | null;
+    type: string | null;
+}
+/** One colour-palette match. */
+export interface ByColourMatch {
+    variantId: string;
+    brand: string;
+    product: string;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    hex: string | null;
+    distance: number;
+    closeness: number;
+    category: MatchCategory | null;
+    oklab: OklabTriple | null;
+}
+/** The `search/colours` response. */
+export interface ByColourResponse {
+    query: {
+        colours: string[];
+        categories?: string[];
+        oklab?: OklabTriple;
+    };
+    count: number;
+    matches: ByColourMatch[];
+}
+/** One item from the pure colour-scalar browse. */
+export interface BrowseResultItem {
+    variantId: string;
+    brand: string;
+    product: string;
+    brandSlug: string | null;
+    productId: string | null;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    scalars: {
+        l: number | null;
+        chroma: number | null;
+        vibrancy: number | null;
+    };
+    retired?: boolean;
+}
+/** A single page of the colour browse. `cursor` is the keyset for the next page. */
+export interface BrowseResponse {
+    results: BrowseResultItem[];
+    cursor?: string;
+}
+export type ColourDictionaryId = OpenEnum<"colour_family" | "colour_mood" | "colour_undertone">;
+export interface ColourFacetTerm {
+    id: string;
+    label: string;
+    aliases: string[];
+    variants: number;
+    brands: number;
+}
+export interface ColourFacetDictionary {
+    attributeId: ColourDictionaryId;
+    name: string;
+    description: string;
+    terms: ColourFacetTerm[];
+}
+export interface ColourFacetsResponse {
+    count: number;
+    dictionaries: ColourFacetDictionary[];
+}
+export interface CategoryNode {
+    key: string;
+    name: string;
+    parentKey: string | null;
+    path: string;
+    level: OpenEnum<"group" | "type">;
+}
+export interface TaxonomyResponse {
+    count: number;
+    categories: CategoryNode[];
+}
+export interface DemandMomentum {
+    state: OpenEnum<"rising" | "fading" | "stable" | "emerging" | "insufficient_volume">;
+    percentChange: number | null;
+    trailingSpecCount: number;
+    priorSpecCount: number;
+}
+export interface CompanionDemand {
+    specCount: number;
+    projectCount: number;
+    momentum: DemandMomentum | null;
+}
+export interface ProjectTypeShare {
+    projectType: string;
+    projectCount: number;
+}
+/** A pairing item backed by real co-specification (order) evidence. */
+export interface CospecPairing {
+    source: "cospec" | "considered";
+    variantId: string;
+    brand: string;
+    product: string;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    brandSlug: string;
+    productId: string;
+    category: string | null;
+    projectCount: number;
+    customerCount: number;
+    lift: number;
+    liftLabel: string;
+    demand: CompanionDemand | null;
+    topProjectTypes: ProjectTypeShare[];
+}
+/** A pairing item topped up from colour palette-similarity (merely looks adjacent). */
+export interface ColourPairing extends MaterialTile {
+    source: "colour";
+    score: number;
+}
+export type PairingItem = CospecPairing | ColourPairing;
+export interface PairingsResponse {
+    seed: MaterialTile;
+    items: PairingItem[];
+    /** How many items came from real order evidence (the cospec arm). */
+    cospecCount: number;
+}
+export interface MaterialResponse {
+    material: MaterialDetail;
+    /** Present only when `include: "siblings"` was requested. */
+    siblings?: MaterialTile[];
+}
+export interface SiblingsResponse {
+    siblings: MaterialTile[];
+}
+/** Batch read of tile projections. */
+export interface MaterialsBatchTileResponse {
+    materials: MaterialTile[];
+    missingIds: string[];
+}
+/** Batch read of detail projections. */
+export interface MaterialsBatchDetailResponse {
+    materials: MaterialDetail[];
+    missingIds: string[];
+}
+export interface ResolveColourResponse {
+    match: {
+        hex: string;
+        name: string;
+        code?: string;
+        libraryId?: string;
+    } | null;
+}
+export interface SuggestColourResponse {
+    suggestions: Array<{
+        term: string;
+        hex: string;
+        libraryId?: string;
+        kind: string;
+    }>;
+}
+export interface AttributeCandidate {
+    attributeId: string;
+    name: string;
+    description: string;
+    score: number;
+    facetable: boolean;
+    blockIds: string[];
+}
+export interface ResolveAttributeResponse {
+    query: string;
+    candidates: AttributeCandidate[];
+}
+export type * from "./catalog-discovery-types.js";
+export interface BySpecMatchedCell {
+    attributeId: string;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+export interface BySpecMatch {
+    variantId: string;
+    brand: string;
+    product: string;
+    variant: string;
+    color: string | null;
+    imageUrl: string | null;
+    hex: string | null;
+    matched: BySpecMatchedCell[];
+    minConfidence: number | null;
+}
+export interface BySpecResponse {
+    criteria: Array<{
+        attribute: string;
+        value: string;
+    }>;
+    totalMatches: number;
+    brandsSpanned: number;
+    matches: BySpecMatch[];
+}
+export interface WhoamiResponse {
+    principal: string;
+    scopes: string[];
+}
+/** A single colour entry in a search palette — exactly one of `hex` or `name`. */
+export interface ColourInput {
+    hex?: string;
+    name?: string;
+    weight?: number;
+    role?: OpenEnum<"any" | "is" | "accent">;
+    sourceName?: string;
+}
+/** A raw incoming image to search by. */
+export type SearchImageInput = {
+    type: "url";
+    url: string;
+} | {
+    type: "base64";
+    data: string;
+};
+/**
+ * The POST `/search` JSON body — the `searchMaterials` contract. Every field is
+ * optional; supply at least one signal (`text`, `colours`, `mood`, `similarTo`,
+ * or `image`). Passed through to the server verbatim.
+ */
+export interface SearchInput {
+    text?: string;
+    textModes?: Array<OpenEnum<"visual" | "lexical">>;
+    colours?: ColourInput[];
+    colourLogic?: OpenEnum<"all" | "any">;
+    colourTolerance?: OpenEnum<"tight" | "normal" | "loose">;
+    colourAppearance?: {
+        lightness?: {
+            min: number;
+            max: number;
+        };
+        warmth?: {
+            min: number;
+            max: number;
+        };
+    };
+    mood?: string;
+    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+    similarTo?: {
+        variantId: string;
+    } | {
+        vector: string;
+    };
+    image?: SearchImageInput;
+    category?: {
+        boost?: string;
+        filter?: string[];
+    };
+    weights?: {
+        image?: number;
+        category?: number;
+        colour?: number;
+        lexical?: number;
+    };
+    filters?: SearchFilter[];
+    limit?: number;
+    cursor?: string;
+    explain?: boolean;
+    collapse?: OpenEnum<"none" | "product">;
+}
+/** Query-string params for the GET `/search` form. */
+export interface SearchGetParams {
+    q?: string;
+    colours?: string;
+    logic?: OpenEnum<"all" | "any">;
+    mood?: string;
+    sort?: OpenEnum<"relevance" | "light" | "dark" | "vivid" | "muted" | "colourful">;
+    tol?: OpenEnum<"tight" | "normal" | "loose">;
+    variantId?: string;
+    limit?: number;
+    /** "0" or "1" — include per-signal `signals` on each result. */
+    explain?: OpenEnum<"0" | "1">;
+}
+/** Params for `search/colours`. */
+export interface ByColourParams {
+    /** A single hex (with or without `#`). */
+    hex?: string;
+    /** A palette — repeated as one `colour` query entry each. */
+    colour?: string | string[];
+    /** OKLab triple (all-or-none). */
+    l?: number;
+    a?: number;
+    b?: number;
+    /** HARD category filter — display names or taxonomy ids (repeatable). */
+    category?: string | string[];
+    limit?: number;
+}
+/** Params for the pure colour `search/browse` surface. */
+export interface BrowseParams {
+    sort: OpenEnum<"light" | "dark" | "vivid" | "muted" | "colourful">;
+    cursor?: string;
+    limit?: number;
+    /** Comma-separated product-type ids to restrict the browse to. */
+    types?: string;
+}
+/** The Material Match request body — exactly one of `imageBase64`, `imageUrl`, `vector`. */
+export interface MatchInput {
+    imageBase64?: string;
+    imageUrl?: string;
+    vector?: string;
+    limit?: number;
+    qualityFloor?: number;
+    categoryTopK?: number;
+    categoryMinBoost?: number;
+    detectionLabel?: string;
+    materialFunction?: string;
+    detectionCategory?: string;
+    requestedType?: OpenEnum<"swatch" | "installation" | "flatplan">;
+}
+/** Options for a batch material read. */
+export interface MaterialsBatchOptions {
+    view?: "tile" | "detail";
+    idKind?: OpenEnum<"variantId" | "materialBankId">;
+}
+/** Options for a pairings read. */
+export interface PairingsOptions {
+    /** Comma-separated coarse category display names; filters both arms. */
+    categories?: string;
+    limit?: number;
+}
+/** Options for `catalog/attributes/resolve`. */
+export interface ResolveAttributeOptions {
+    limit?: number;
+    facetableOnly?: boolean;
+}
+/** Options for `search/specifications`. */
+export interface BySpecOptions {
+    limit?: number;
+}
+/** A resolved seed material (identity block shared by the demand reads). */
+export interface DemandSeed {
+    variantId: string;
+    brand: string;
+    product: string;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    brandSlug: string;
+    productId: string;
+}
+export interface DemandQuarter {
+    quarter: string;
+    specCount: number;
+    projectCount: number;
+}
+/** Headline demand stats for a seed: counts, quarterly series, momentum. */
+export interface MaterialDemandStats {
+    specCount: number;
+    projectCount: number;
+    customerCount: number;
+    byQuarter: DemandQuarter[];
+    momentum: DemandMomentum;
+}
+/** `getMaterialDemand` result, passed through verbatim by the `/demand` route. */
+export interface MaterialDemandResult {
+    found: boolean;
+    query: string;
+    seed: DemandSeed | null;
+    window: "trailing_36mo";
+    demand: MaterialDemandStats | null;
+}
+/**
+ * `getCoSpecifiedMaterials` result, passed through verbatim. The `companions`
+ * list (materials specified alongside the seed) is included but left loosely
+ * typed — there is no captured fixture to pin its full shape.
+ */
+export interface CoSpecifiedResult {
+    found: boolean;
+    resolution: OpenEnum<"resolved" | "ambiguous" | "not_found">;
+    query: string;
+    seed: DemandSeed | null;
+    seedCategory: string | null;
+    seedAlternatives: DemandSeed[];
+    companions?: unknown[];
+}
+/** The `/api/v1/demand` envelope — both domain reads side by side, verbatim. */
+export interface DemandResponse {
+    query: string;
+    demand: MaterialDemandResult;
+    cospec: CoSpecifiedResult;
+}
+export interface CoordinateSeed extends DemandSeed {
+    /** The input reference this seed resolved from. */
+    resolvedFrom: string;
+}
+export interface CoordinateCompanion {
+    variantId: string;
+    brand: string;
+    product: string;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    brandSlug: string;
+    productId: string;
+    totalLift: number;
+    liftLabel: string;
+    seedMatchCount: number;
+    seedContributions: Array<{
+        seedVariantId: string;
+        lift: number;
+    }>;
+    demand: CompanionDemand | null;
+    swatches: Array<{
+        hex: string;
+        proportion: number;
+    }>;
+    /** Annotate-only appearance similarity — never reorders companions in v1. */
+    colourFit: number | null;
+}
+export interface CoordinateResponse {
+    seeds: CoordinateSeed[];
+    unresolved: string[];
+    window: "trailing_36mo";
+    companions: CoordinateCompanion[];
+}
+export interface ExtractedPalette {
+    colors: Array<{
+        hex: string;
+        name: string;
+        proportion: number;
+    }>;
+    dominant: {
+        family: string;
+        hex: string;
+        name: string;
+        oklch: string;
+    } | null;
+    mood: string;
+}
+export interface ExtractPaletteResponse {
+    palette: ExtractedPalette | null;
+}
+export interface SpecFacetValue {
+    value: string;
+    variants: number;
+    brands: number;
+    label?: string;
+}
+export interface SpecFacet {
+    attributeId: string;
+    name: string;
+    isArray: boolean;
+    brands: number;
+    values: SpecFacetValue[];
+    description?: string;
+}
+export interface SpecFacetsListResponse {
+    mode: "facets";
+    count: number;
+    facets: SpecFacet[];
+}
+export interface SpecFacetsDistributionResponse {
+    mode: "distribution";
+    attributeId: string;
+    count: number;
+    values: SpecFacetValue[];
+}
+export interface ApplicableSpecAttribute {
+    id: string;
+    name: string;
+    valueKind: string;
+    required: boolean;
+}
+export interface ApplicableSpecBlock {
+    blockId: string;
+    name: string;
+    applicability: OpenEnum<"required" | "recommended" | "optional" | "unusual">;
+    attributes: ApplicableSpecAttribute[];
+}
+export interface ApplicableSpecsResponse {
+    found: boolean;
+    productType: {
+        id: string;
+        name: string;
+    } | null;
+    blocks: ApplicableSpecBlock[];
+    hint?: string;
+}
+export interface GlossaryAttributeMatch {
+    kind: "attribute";
+    id: string;
+    name: string;
+    description: string;
+    valueKind: string;
+    unit?: string;
+    facetable: boolean;
+    comparable: boolean;
+    dictionaryId?: string;
+    usedInBlocks: string[];
+}
+export interface GlossaryValueMatch {
+    kind: "value";
+    id: string;
+    label: string;
+    description?: string;
+    aliases: string[];
+    dictionaryId: string;
+    dictionaryName: string;
+    attributeIds: string[];
+}
+export interface GlossaryTermResponse {
+    found: boolean;
+    term: string;
+    match: GlossaryAttributeMatch | GlossaryValueMatch | null;
+    alternates?: Array<{
+        kind: OpenEnum<"attribute" | "value">;
+        id: string;
+        label: string;
+    }>;
+}
+export interface BrandProfile {
+    id: string;
+    slug: string;
+    name: string;
+    marketSegment: string;
+    headquartersCity: string | null;
+    headquartersCountry: string | null;
+    parentBrand: {
+        id: string;
+        name: string;
+    } | null;
+    positioning: string | null;
+    ownershipType: string | null;
+    foundedYear: number | null;
+    description: string | null;
+    website: string | null;
+}
+export interface BrandProfileResponse {
+    found: boolean;
+    query: string;
+    brand: BrandProfile | null;
+    /** Trade / spec signals ON RECORD, keyed by attribute id. Absent = no value held (never infer false). */
+    trade: Record<string, boolean | string>;
+    links: Array<{
+        label: string;
+        url: string;
+    }>;
+    alternates: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/** Seed a demand read by EXACTLY ONE of `variantId` or `material`. */
+export interface DemandParams {
+    variantId?: string;
+    material?: string;
+}
+/** Body for `POST /api/v1/pairings/coordinate`. */
+export interface CoordinateInput {
+    materials?: string[];
+    variantIds?: string[];
+    projectType?: string;
+    limit?: number;
+}
+/** Body for `POST /api/v1/search/palettes/extract`. */
+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;
+}
+/** Options for a cacheable GET batch read (`materialsCached`). */
+export interface MaterialsBatchGetOptions extends MaterialsBatchOptions {
+}
+/** Options for `brands/{slug}`. */
+export interface BrandOptions {
+    /** Alternate fuzzy query; takes precedence over the path slug when present. */
+    q?: string;
+}