@instruments/materialgraph 0.18.0 → 0.19.0

package/types.d.ts

@@ -32,18 +32,12 @@ import type { MaterialDetail, MaterialTile } from "./material-types.js";
 import type { QueryUnderstanding } from "./query-understanding-types.js";
 import type { CollapsedVariant, SearchAnatomyMember } from "./search-collapse-types.js";
 import type { SearchDisambiguation, SearchSuggestion } from "./search-refinement-types.js";
-import type { CompoundColourConstraintReceipt, CompoundFormConstraintReceipt, SearchExecutionPlan, SearchMode, SearchRerankReport, SearchResponseExplainReceipts } from "./search-response-receipt-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 * from "./search-response-receipt-types.js";
+export type { MoodInterpretation } from "./search-mood-types.js";
 export type OpenEnum<T extends string> = T | (string & {});
-/**
- * A JSON value, recursively — exactly what survives a `jsonb` round-trip
- * unchanged. Used where a payload's SHAPE belongs to its producer but its values
- * must still be JSON: `Date`, `bigint`, `undefined`, and functions are not.
- */
-export type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
+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.
@@ -120,6 +114,8 @@ export interface VisualMeaning {
  * `visualMeanings` is not "this material has no visual meaning".
  */
 export interface SearchResultItem {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
     /** Opaque — round-trip verbatim into `material()`, `pairings()`, `similarTo`. */
     variantId: VariantId;
     brand: string;
@@ -134,7 +130,7 @@ export interface SearchResultItem {
      * Populated on EVERY lane: `search()` (all four arms), `match()`, and
      * `matchStream()` frames.
      * ABSENT means no MB identity is known for the variant — never that the SKU
-     * cannot be ordered. Presence is the orderability tell; absence is silence.
+     * cannot be ordered. Presence identifies the source; it does not establish sampleability.
      */
     materialBankId?: string;
     manufacturerCode?: string;
@@ -276,6 +272,8 @@ export interface SearchResultItem {
  * card does not carry.
  */
 export interface SearchCardItem {
+    /** Accepted sampleability fact. Absent means unknown, never false. */
+    sampleable?: boolean;
     /** Opaque — round-trip verbatim. */
     variantId: VariantId;
     productId: ProductId | null;
@@ -380,14 +378,6 @@ export interface SearchFacets {
     absent: SearchAbsentFacet[];
     counts: Record<string, SearchFacetCount>;
 }
-/** Inspectable metadata for an opaque, principal-bound search refinement receipt. */
-export interface SearchRefinementReceipt {
-    token: string;
-    expiresAt: string;
-    poolSize: number;
-    schemaVersion: string;
-    projectionVersion: number;
-}
 /**
  * The search response envelope. `view` discriminates the `results` union:
  * `"full"` (default) carries {@link SearchResultItem}s, `"card"` the lean
@@ -438,6 +428,11 @@ export interface SearchResponse extends SearchResponseExplainReceipts {
     timings?: Record<string, number>;
     /** A detected mood term overridden by a stronger colour reading. */
     supersededMoodId?: string;
+    /**
+     * Explicit standard-search mood reading; null ids mean no selected mood.
+     * Absent when mood was not evaluated or an older server produced the result.
+     */
+    moodInterpretation?: import("./search-mood-types.js").MoodInterpretation;
     /**
      * Present when the query had multiple defensible readings. Says which one
      * ran, or leaves every reading non-default when the engine chose none. Every
@@ -713,6 +708,8 @@ export interface PairingsOptions {
     categories?: string;
     /** Page size, 1–24 inclusive (default 12). The server rejects (400), not clamps, values outside this range. */
     limit?: number;
+    /** Return sampled order evidence only, without board or colour fallback. */
+    sampledOnly?: boolean;
     /** Graph-owned order applied within fixed cospec → considered → colour tiers. */
     order?: PairingOrderMode;
     /** Optional Material Bank/orderable gate; requires an explicit `order`. */