@instruments/materialgraph 0.24.0 → 0.26.0

package/types.d.ts

@@ -1,4 +1,3 @@
-export type { SearchResponse } from "./search-response-types.js";
 import type { ResponseAttribution } from "./attribution-types.js";
 import type { BySpecVerdict } from "./by-spec-types.js";
 /**
@@ -36,6 +35,7 @@ import type { MoodInterpretation } from "./search-mood-types.js";
 import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
 import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRefinementReceipt, SearchRerankReport, SearchResponseExplainReceipts } from "./search-response-receipt-types.js";
 import type { SearchWindowReceipt } from "./search-window-types.js";
+export type { SearchResponse } from "./search-response-types.js";
 export type * from "./search-response-receipt-types.js";
 export type { MoodInterpretation } from "./search-mood-types.js";
 export type OpenEnum<T extends string> = T | (string & {});
@@ -44,7 +44,7 @@ export type { JsonValue } from "./json-value-types.js";
  * One palette swatch of a material's main image — colour DERIVED FROM PRODUCT
  * IMAGERY, so read it as visual likeness, never as a declared colour spec.
  */
-export interface PaletteSwatch {
+export type PaletteSwatch = {
     hex: string;
     proportion: number;
     /** Stored human colour name for the swatch, when one was extracted. */
@@ -56,21 +56,21 @@ export interface PaletteSwatch {
      * derived here" — never "achromatic".
      */
     oklab?: OklabTriple;
-}
+};
 /** Loose colour metadata for a search result's main image; every field is independently optional. */
-export interface ColourMeta {
+export type ColourMeta = {
     mood?: string;
     dominantFamily?: string;
     dominantHex?: string;
-}
+};
 /** OKLab triple. */
-export interface OklabTriple {
+export type OklabTriple = {
     l: number;
     a: number;
     b: number;
-}
+};
 /** The material's dominant-colour block (tile/detail projections). */
-export interface MaterialColour {
+export type MaterialColour = {
     dominantHex: string | null;
     hsl: {
         h: number;
@@ -80,12 +80,12 @@ export interface MaterialColour {
     oklab: OklabTriple | null;
     chroma: number | null;
     vibrancy: number | null;
-}
+};
 /** Where the served image came from. */
 export type ImageSource = OpenEnum<"r2" | "origin">;
 export type { DimensionEntry, MaterialAvailability, MaterialDetail, MaterialFacet, MaterialSuccessor, MaterialTile, SiblingTile, } from "./material-types.js";
 /** Per-signal scores, present on a result when `explain` was requested. */
-export interface SearchResultSignals {
+export type SearchResultSignals = {
     /** Voyage similarity in the dedicated variant text-portrait space. */
     portrait?: number | null;
     image: number | null;
@@ -94,9 +94,9 @@ export interface SearchResultSignals {
     lexical: number | null;
     /** Compatibility slot for retired seeded secondary scoring; currently null. */
     text: number | null;
-}
+};
 /** An accepted/measured visual meaning — descriptive evidence, never a ranking cause. */
-export interface VisualMeaning {
+export type VisualMeaning = {
     id: string;
     label: string;
     values: string[];
@@ -105,7 +105,7 @@ export interface VisualMeaning {
     sourceBasis?: string;
     version?: string;
     appliedAt?: string;
-}
+};
 /**
  * One material in a search / match result list.
  *
@@ -115,7 +115,7 @@ export interface VisualMeaning {
  * answer is "no". A missing `retired` is not "still current"; a missing
  * `visualMeanings` is not "this material has no visual meaning".
  */
-export interface SearchResultItem {
+export type SearchResultItem = {
     /** This hit's attribution key — see {@link ResponseAttribution}. Opaque. */
     resultId?: string;
     /** Accepted sampleability fact. Absent means unknown, never false. */
@@ -266,7 +266,7 @@ export interface SearchResultItem {
      * attribute rather than a list of candidates.
      */
     attributes?: Record<string, string | string[] | null>;
-}
+};
 /**
  * A feed total with its honesty basis — THE CLAIM ABOUT THE MATCH SET, which is
  * a different number from `results.length` (this page).
@@ -285,29 +285,29 @@ export interface SearchResultItem {
  * A response with no `counts` at all states no total: `count: true` is opt-in,
  * and the absence of a total is not a total of zero.
  */
-export interface CountedTotal {
+export type CountedTotal = {
     value: number;
     basis: OpenEnum<"exact" | "lowerBound">;
-}
+};
 /**
  * Feed counts — present ONLY under `count:true` or `collapse:"product"`. This is
  * the corpus-level claim; `results.length` is the page. Never report one as the
  * other.
  */
-export interface SearchCounts {
+export type SearchCounts = {
     variants: CountedTotal;
     products?: CountedTotal;
-}
+};
 /**
  * One value within a facet's counts: the CANONICAL token (send it back verbatim
  * as a filter term), its display label, and how many variants in the counted
  * set carry it.
  */
-export interface SearchFacetValue {
+export type SearchFacetValue = {
     value: string;
     label: string;
     variants: number;
-}
+};
 /**
  * One facet's counts. `basis` is the honesty label, and — per the negotiated
  * MG-1010 contract — its union is CLOSED: exactly `"exact"` or `"lowerBound"`,
@@ -318,11 +318,11 @@ export interface SearchFacetValue {
  * pool-counted value is NEVER `exact`. `truncated` is ALWAYS present: true
  * when more distinct values existed beyond the reported list.
  */
-export interface SearchFacetCount {
+export type SearchFacetCount = {
     values: SearchFacetValue[];
     truncated: boolean;
     basis: "exact" | "lowerBound";
-}
+};
 /**
  * A requested facet that was not counted, with its reason: `"unsupported"` —
  * the id is known but facet counting does not cover it; `"timeout"` — the
@@ -330,22 +330,22 @@ export interface SearchFacetCount {
  * rail could not count; the page is intact). Render it as "couldn't count",
  * never as zero.
  */
-export interface SearchAbsentFacet {
+export type SearchAbsentFacet = {
     facetId: string;
     reason: OpenEnum<"unsupported" | "timeout">;
-}
+};
 /**
  * Per-query facet counts (MG-1010) — present ONLY when the request sent
  * `facetCounts`. `counts` is keyed by requested facet id; every requested
  * facet not in `absent` has an entry, including empty ones. `poolSize` is
  * present exactly when the counts are pool-derived.
  */
-export interface SearchFacets {
+export type SearchFacets = {
     poolSize?: number;
     requested: string[];
     absent: SearchAbsentFacet[];
     counts: Record<string, SearchFacetCount>;
-}
+};
 /**
  * The search response envelope. `view` discriminates the `results` union:
  * `"full"` (default) carries {@link SearchResultItem}s, `"card"` the lean
@@ -358,7 +358,7 @@ export interface SearchFacets {
  * you asked for it. Follow `cursor` for the rest. "I found 24 materials" is
  * wrong whenever `limit` was 24.
  */
-export interface SearchData extends SearchResponseExplainReceipts {
+export type SearchData = {
     /** Result attribution — see {@link ResponseAttribution}. `basis` is `mode` verbatim here. */
     attribution?: ResponseAttribution;
     view: OpenEnum<"full" | "card">;
@@ -410,6 +410,7 @@ export interface SearchData extends SearchResponseExplainReceipts {
     facets?: SearchFacets;
     /** Receipt that narrows the exact finalized pool behind lower-bound facets. */
     refinement?: SearchRefinementReceipt;
+    /** One or more sentences written for a person; absent when there is nothing to say. */
     note?: string;
     timings?: Record<string, number>;
     /** A detected mood term overridden by a stronger colour reading. */
@@ -438,51 +439,51 @@ export interface SearchData extends SearchResponseExplainReceipts {
     query?: Record<string, unknown>;
     /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
     seed?: MaterialTile | Record<string, unknown>;
-}
+} & SearchResponseExplainReceipts;
 export type ColourDictionaryId = OpenEnum<"colour_family" | "colour_mood" | "colour_undertone">;
-export interface ColourFacetTerm {
+export type ColourFacetTerm = {
     id: string;
     label: string;
     aliases: string[];
     variants: number;
     brands: number;
-}
-export interface ColourFacetDictionary {
+};
+export type ColourFacetDictionary = {
     attributeId: ColourDictionaryId;
     name: string;
     description: string;
     terms: ColourFacetTerm[];
-}
-export interface ColourFacetsResponse {
+};
+export type ColourFacetsResponse = {
     count: number;
     dictionaries: ColourFacetDictionary[];
-}
-export interface CategoryNode {
+};
+export type CategoryNode = {
     key: string;
     name: string;
     parentKey: string | null;
     path: string;
     level: OpenEnum<"group" | "type">;
-}
-export interface TaxonomyResponse {
+};
+export type TaxonomyResponse = {
     count: number;
     categories: CategoryNode[];
-}
-export interface DemandMomentum {
+};
+export type DemandMomentum = {
     state: OpenEnum<"rising" | "fading" | "stable" | "emerging" | "insufficient_volume">;
     percentChange: number | null;
     trailingSpecCount: number;
     priorSpecCount: number;
-}
-export interface CompanionDemand {
+};
+export type CompanionDemand = {
     specCount: number;
     projectCount: number;
     momentum: DemandMomentum | null;
-}
-export interface ProjectTypeShare {
+};
+export type ProjectTypeShare = {
     projectType: string;
     projectCount: number;
-}
+};
 /**
  * A pairing item from the behavioural arm — real order evidence, or board
  * curation when this seed has no order edges.
@@ -499,7 +500,7 @@ export interface ProjectTypeShare {
  *
  * See {@link ColourPairing} for the third, non-evidential arm.
  */
-export interface CospecPairing {
+export type CospecPairing = {
     /** The evidence tier. `cospec` = orders; `considered` = boards. Read it before phrasing. */
     source: "cospec" | "considered";
     /** Opaque — round-trip verbatim. */
@@ -536,29 +537,29 @@ export interface CospecPairing {
     topProjectTypes: ProjectTypeShare[];
     /** Graph-owned colour ranking facts, present only for an explicitly ordered rail. */
     ranking?: PairingRanking;
-}
+};
 /**
  * A pairing item topped up from colour palette-similarity — a LOOK-ALIKE, not
  * evidence. Nobody ordered these together and nobody boarded them together; the
  * palettes sit near each other in OKLab. Say "shares a palette with" and never
  * "specified together" or "often paired with".
  */
-export interface ColourPairing extends MaterialTile {
+export type ColourPairing = {
     source: "colour";
     score: number;
     /** Graph-owned colour ranking facts, present only for an explicitly ordered rail. */
     ranking?: PairingRanking;
-}
+} & MaterialTile;
 export type PairingOrderMode = "relevance" | "lightness_asc" | "lightness_desc";
 export type PairingCorpus = "all" | "material_bank";
-export interface PairingRanking {
+export type PairingRanking = {
     anchorColourSimilarity: number | null;
     lightness: number | null;
     anchorColourSimilarityMeasurable: boolean;
     lightnessMeasurable: boolean;
     basis: OpenEnum<"dominant_colour_oklab">;
-}
-export interface PairingOrdering {
+};
+export type PairingOrdering = {
     requested: OpenEnum<PairingOrderMode>;
     applied: OpenEnum<PairingOrderMode>;
     direction: OpenEnum<"ascending" | "descending">;
@@ -570,14 +571,14 @@ export interface PairingOrdering {
     };
     missingValues: OpenEnum<"last">;
     tieBreak: OpenEnum<"variantId_asc">;
-}
+};
 /**
  * One pairing, discriminated by `source` into three tiers of very different
  * strength: `cospec` (real orders) > `considered` (board activity) > `colour`
  * (palette look-alike). Branch on `source` before you write a sentence about it.
  */
 export type PairingItem = CospecPairing | ColourPairing;
-export interface PairingsResponse {
+export type PairingsResponse = {
     seed: MaterialTile;
     /** A rail, not a ranked corpus — mixed evidence tiers, capped by `limit`. */
     items: PairingItem[];
@@ -598,70 +599,70 @@ export interface PairingsResponse {
     ordering?: PairingOrdering;
     /** Opaque continuation bound to the seed, filters, corpus, and order. */
     nextCursor?: Cursor;
-}
-export interface MaterialResponse {
+};
+export type MaterialResponse = {
     material: MaterialDetail;
     /** Present only when `include: "siblings"` was requested. */
     siblings?: SiblingTile[];
-}
-export interface SiblingsResponse {
+};
+export type SiblingsResponse = {
     siblings: SiblingTile[];
-}
+};
 /**
  * Batch read of tile projections. `materials` is NOT positional — resolve by
  * `variantId`, and read `missingIds` rather than inferring absence from length.
  */
-export interface MaterialsBatchTileResponse {
+export type MaterialsBatchTileResponse = {
     materials: MaterialTile[];
     /** Requested ids that resolved to nothing. Echoed verbatim, opaque. */
     missingIds: VariantId[];
-}
+};
 /**
  * Batch read of detail projections. `materials` is NOT positional — resolve by
  * `variantId`, and read `missingIds` rather than inferring absence from length.
  */
-export interface MaterialsBatchDetailResponse {
+export type MaterialsBatchDetailResponse = {
     materials: MaterialDetail[];
     /** Requested ids that resolved to nothing. Echoed verbatim, opaque. */
     missingIds: VariantId[];
-}
-export interface SuggestColourResponse {
-    suggestions: Array<{
+};
+export type SuggestColourResponse = {
+    suggestions: {
         term: string;
         hex: string;
         libraryId?: string;
         kind: string;
-    }>;
-}
-export interface AttributeCandidate {
+    }[];
+};
+export type AttributeCandidate = {
     attributeId: string;
     name: string;
     description: string;
     score: number;
     facetable: boolean;
     blockIds: string[];
-}
-export interface ResolveAttributeResponse {
+};
+export type ResolveAttributeResponse = {
     query: string;
     candidates: AttributeCandidate[];
-}
+};
 export type * from "./catalog-discovery-types.js";
 export type * from "./resolve-types.js";
 export type * from "./resolve-colour-types.js";
 export type * from "./suggest-types.js";
 export type * from "./by-spec-types.js";
-export interface WhoamiResponse {
+export type WhoamiResponse = {
     principal: string;
     scopes: string[];
-}
+};
 /** A single colour entry in a search palette — exactly one of `hex` or `name`. */
-export interface ColourInput {
+export type 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";
@@ -672,7 +673,7 @@ export type SearchImageInput = {
 };
 export type { SearchGetParams, SearchInput } from "./search-request-types.js";
 /** Options for a batch material read. */
-export interface MaterialsBatchOptions {
+export type MaterialsBatchOptions = {
     /** Projection depth. `tile` omits fields rather than reporting them absent. */
     view?: "tile" | "detail";
     /**
@@ -682,9 +683,9 @@ export interface MaterialsBatchOptions {
      * `missingIds`, not an error.
      */
     idKind?: OpenEnum<"variantId" | "materialBankId">;
-}
+};
 /** Options for a pairings read. */
-export interface PairingsOptions {
+export type PairingsOptions = {
     /** Comma-separated coarse category display names; filters both arms. */
     categories?: string;
     /** Page size, 1–24 inclusive (default 12). The server rejects (400), not clamps, values outside this range. */
@@ -697,14 +698,14 @@ export interface PairingsOptions {
     corpus?: PairingCorpus;
     /** The previous response's `nextCursor`, passed back verbatim. */
     cursor?: Cursor;
-}
+};
 /** Options for `catalog/attributes/resolve`. */
-export interface ResolveAttributeOptions {
+export type ResolveAttributeOptions = {
     limit?: number;
     facetableOnly?: boolean;
-}
+};
 /** Options for `search/specifications`. */
-export interface BySpecOptions {
+export type BySpecOptions = {
     limit?: number;
     /**
      * Numeric range criteria as `attribute:min..max` strings, ANDed with the
@@ -713,14 +714,14 @@ export interface BySpecOptions {
      * token with neither is refused by the server rather than matching everything.
      */
     ranges?: string[];
-}
+};
 export type * from "./demand-types.js";
 /** One quarter's tally. Sparse across a series — an absent quarter is not a zero. */
-export interface DemandQuarter {
+export type DemandQuarter = {
     quarter: string;
     specCount: number;
     projectCount: number;
-}
+};
 /**
  * Which behavioural signal a demand read is scoped to — and therefore what a
  * number drawn from it may honestly be called.
@@ -736,12 +737,12 @@ export interface DemandQuarter {
  */
 export type DemandSignal = OpenEnum<"sampled" | "considered" | "specified">;
 export type * from "./demand-batch-types.js";
-export interface ExtractedPalette {
-    colors: Array<{
+export type ExtractedPalette = {
+    colors: {
         hex: string;
         name: string;
         proportion: number;
-    }>;
+    }[];
     dominant: {
         family: string;
         hex: string;
@@ -749,24 +750,24 @@ export interface ExtractedPalette {
         oklch: string;
     } | null;
     mood: string;
-}
-export interface ExtractPaletteResponse {
+};
+export type ExtractPaletteResponse = {
     palette: ExtractedPalette | null;
-}
+};
 export type * from "./spec-facet-types.js";
-export interface ApplicableSpecAttribute {
+export type ApplicableSpecAttribute = {
     id: string;
     name: string;
     valueKind: string;
     required: boolean;
-}
-export interface ApplicableSpecBlock {
+};
+export type ApplicableSpecBlock = {
     blockId: string;
     name: string;
     applicability: OpenEnum<"required" | "recommended" | "optional" | "unusual">;
     attributes: ApplicableSpecAttribute[];
-}
-export interface ApplicableSpecsResponse {
+};
+export type ApplicableSpecsResponse = {
     found: boolean;
     productType: {
         id: string;
@@ -774,8 +775,8 @@ export interface ApplicableSpecsResponse {
     } | null;
     blocks: ApplicableSpecBlock[];
     hint?: string;
-}
-export interface GlossaryAttributeMatch {
+};
+export type GlossaryAttributeMatch = {
     kind: "attribute";
     id: string;
     name: string;
@@ -786,8 +787,8 @@ export interface GlossaryAttributeMatch {
     comparable: boolean;
     dictionaryId?: string;
     usedInBlocks: string[];
-}
-export interface GlossaryValueMatch {
+};
+export type GlossaryValueMatch = {
     kind: "value";
     id: string;
     label: string;
@@ -796,18 +797,18 @@ export interface GlossaryValueMatch {
     dictionaryId: string;
     dictionaryName: string;
     attributeIds: string[];
-}
-export interface GlossaryTermResponse {
+};
+export type GlossaryTermResponse = {
     found: boolean;
     term: string;
     match: GlossaryAttributeMatch | GlossaryValueMatch | null;
-    alternates?: Array<{
+    alternates?: {
         kind: OpenEnum<"attribute" | "value">;
         id: string;
         label: string;
-    }>;
-}
-export interface BrandProfile {
+    }[];
+};
+export type BrandProfile = {
     id: string;
     slug: string;
     name: string;
@@ -823,34 +824,33 @@ export interface BrandProfile {
     foundedYear: number | null;
     description: string | null;
     website: string | null;
-}
-export interface BrandProfileResponse {
+};
+export type 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<{
+    links: {
         label: string;
         url: string;
-    }>;
-    alternates: Array<{
+    }[];
+    alternates: {
         id: string;
         name: string;
-    }>;
-}
+    }[];
+};
 /** Body for `POST /api/v1/search/palettes/extract`. */
-export interface ExtractPaletteInput {
+export type 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 {
-}
+export type MaterialsBatchGetOptions = MaterialsBatchOptions;
 /** Options for `brands/{brandSlug}`. */
-export interface BrandOptions {
+export type BrandOptions = {
     /** Alternate fuzzy query; takes precedence over the path slug when present. */
     q?: string;
-}
+};