@instruments/materialgraph 0.3.0 → 0.5.0

package/client-browse.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The `browse` namespace's implementation — the paged colour-ordered walk of the
+ * corpus behind `client.browse(...)` and `client.browse.pages(...)`.
+ *
+ * Lifted out of `client.ts` for the repository's source-file size budget. These
+ * were already private implementations behind a public namespace, so nothing
+ * about the client's surface changes: `client.browse` is still a callable with a
+ * `.pages()` generator, and the class still owns the transport. What moved is
+ * the pagination LOOP, which is the only real logic here and the only part worth
+ * testing on its own.
+ */
+import type { BrowseParams, BrowseResponse } from "./types.js";
+/** `client.browse(...)` — callable for one page, `.pages()` for the whole walk. */
+export interface BrowseNamespace {
+    (params: BrowseParams, signal?: AbortSignal): Promise<BrowseResponse>;
+    pages(params: BrowseParams, signal?: AbortSignal): AsyncGenerator<BrowseResponse, void, unknown>;
+}
+/** Fetch one page. The client supplies this, so the transport stays private. */
+export type BrowsePageFetcher = (params: BrowseParams, signal?: AbortSignal) => Promise<BrowseResponse>;
+/**
+ * The query string for one browse page — the four params the route reads, named
+ * here so the client method and the pagination loop cannot disagree about them.
+ */
+export declare function browseQuery(params: BrowseParams): {
+    sort: BrowseParams["sort"];
+    cursor: BrowseParams["cursor"];
+    limit: BrowseParams["limit"];
+    types: BrowseParams["types"];
+};
+/**
+ * Walk every page from `params.cursor` onward.
+ *
+ * Stops on the first page that reports no next cursor OR comes back empty. Both
+ * conditions matter: a server that keeps handing out a cursor for an exhausted
+ * scan would otherwise spin here forever, and an infinite generator is a hang,
+ * not an error anyone can see.
+ */
+export declare function browsePages(fetchPage: BrowsePageFetcher, params: BrowseParams, signal?: AbortSignal): AsyncGenerator<BrowseResponse, void, unknown>;
+/**
+ * Build the callable-with-`.pages()` object the client exposes as `browse`.
+ *
+ * @example
+ * const page = await client.browse({ sort: "lightest" });
+ * for await (const page of client.browse.pages({ sort: "lightest" })) { … }
+ */
+export declare function createBrowseNamespace(fetchPage: BrowsePageFetcher): BrowseNamespace;

package/client-browse.js

@@ -0,0 +1,42 @@
+/**
+ * The query string for one browse page — the four params the route reads, named
+ * here so the client method and the pagination loop cannot disagree about them.
+ */
+export function browseQuery(params) {
+    return {
+        sort: params.sort,
+        cursor: params.cursor,
+        limit: params.limit,
+        types: params.types,
+    };
+}
+/**
+ * Walk every page from `params.cursor` onward.
+ *
+ * Stops on the first page that reports no next cursor OR comes back empty. Both
+ * conditions matter: a server that keeps handing out a cursor for an exhausted
+ * scan would otherwise spin here forever, and an infinite generator is a hang,
+ * not an error anyone can see.
+ */
+export async function* browsePages(fetchPage, params, signal) {
+    let cursor = params.cursor;
+    for (;;) {
+        const page = await fetchPage({ ...params, cursor }, signal);
+        yield page;
+        if (page.cursor === undefined || page.results.length === 0)
+            return;
+        cursor = page.cursor;
+    }
+}
+/**
+ * Build the callable-with-`.pages()` object the client exposes as `browse`.
+ *
+ * @example
+ * const page = await client.browse({ sort: "lightest" });
+ * for await (const page of client.browse.pages({ sort: "lightest" })) { … }
+ */
+export function createBrowseNamespace(fetchPage) {
+    const browse = (params, signal) => fetchPage(params, signal);
+    browse.pages = (params, signal) => browsePages(fetchPage, params, signal);
+    return browse;
+}

package/client.d.ts

@@ -1,4 +1,6 @@
 import { type RateLimit } from "./errors.js";
+import { type BrowseNamespace } from "./client-browse.js";
+export type { BrowseNamespace } from "./client-browse.js";
 import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
 import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
 import type { MatchStreamEvent } from "./match-stream-types.js";
@@ -11,7 +13,7 @@ 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, DemandBatchInput, DemandBatchResponse, 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";
+import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, ByColourParams, ByColourResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, 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, SuggestOptions, SuggestResponse, 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 {
@@ -22,10 +24,6 @@ export interface MaterialGraphClientOptions {
     /** 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;
@@ -130,6 +128,18 @@ export declare class MaterialGraphClient {
     suggestColour(q: string, options?: {
         limit?: number;
     }, signal?: AbortSignal): Promise<SuggestColourResponse>;
+    /**
+     * Entity typeahead across products, brands and categories
+     * (GET `/api/v1/search/suggest`). Built for per-keystroke use: one indexed
+     * lookup, no embedding call and no model. Every suggestion carries the
+     * `refId` it resolves to — a product id, a brand slug, or a product-type key
+     * — so selecting one should navigate to that entity rather than re-running
+     * `label` as a search.
+     *
+     * @example
+     * const { suggestions } = await client.suggest("carr", { kind: "product" });
+     */
+    suggest(q: string, options?: SuggestOptions, signal?: AbortSignal): Promise<SuggestResponse>;
     /** 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. */

package/client.js

@@ -2,6 +2,8 @@ import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
 import { findSdkOperation } from "./operations.js";
 import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { browseQuery, createBrowseNamespace } from "./client-browse.js";
+import { suggestQuery } from "./suggest-types.js";
 import { matchStream as matchStreamCall } from "./match-stream.js";
 import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
 import { CodesClient } from "./codes-client.js";
@@ -51,15 +53,14 @@ export class MaterialGraphClient {
             fetch: options.fetch ?? globalThis.fetch,
         });
         this.baseUrl = this.#transport.baseUrl;
-        const browse = (params, signal) => this.#browsePage(params, signal);
-        browse.pages = (params, signal) => this.#browsePages(params, signal);
-        this.browse = browse;
+        this.browse = createBrowseNamespace((params, signal) => this.#get("search_browse_by_colour", browseQuery(params), signal));
         this.codes = new CodesClient({
             get: (operationId, query, signal) => this.#get(operationId, query, signal),
             post: (operationId, body, signal) => this.#post(operationId, body, signal),
         });
         this.colours = new ColoursClient({
             get: (operationId, query, signal) => this.#get(operationId, query, signal),
+            post: (operationId, body, signal) => this.#post(operationId, body, signal),
         });
     }
     get lastRateLimit() {
@@ -173,25 +174,6 @@ export class MaterialGraphClient {
             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) {
@@ -205,6 +187,20 @@ export class MaterialGraphClient {
     suggestColour(q, options, signal) {
         return this.#get("suggest_colour_names", { q, limit: options?.limit }, signal);
     }
+    /**
+     * Entity typeahead across products, brands and categories
+     * (GET `/api/v1/search/suggest`). Built for per-keystroke use: one indexed
+     * lookup, no embedding call and no model. Every suggestion carries the
+     * `refId` it resolves to — a product id, a brand slug, or a product-type key
+     * — so selecting one should navigate to that entity rather than re-running
+     * `label` as a search.
+     *
+     * @example
+     * const { suggestions } = await client.suggest("carr", { kind: "product" });
+     */
+    suggest(q, options, signal) {
+        return this.#get("search_suggest", suggestQuery(q, options), signal);
+    }
     // ── Catalog ──────────────────────────────────────────────────────────────────
     /** Resolve a free-text spec phrase to canonical attribute ids (GET `/api/v1/catalog/attributes/resolve`). */
     resolveAttribute(q, options, signal) {

package/colours-client.d.ts

@@ -1,26 +1,31 @@
 /**
- * The colour AGGREGATE surface, namespaced as `mg.colours`.
+ * The colour surface, namespaced as `mg.colours` — the aggregate reads
+ * (`stats`, `profiles`) plus MULTI-COLOUR search (`palette`, `gradient`).
  *
- * Two reads that answer the same question at two altitudes — "how much colour
- * does the graph hold at all" (`stats`) and "what colours does this category
- * come in" (`profiles`) — so they live together rather than as two more flat
- * methods on an already-large client facade. `mg.codes` and `mg.browse` set the
- * precedent for a namespace when a capability is a small family rather than a
- * single verb.
+ * One colour family rather than four more flat methods on an already-large
+ * client facade: "how much colour does the graph hold at all" (`stats`), "what
+ * colours does this category come in" (`profiles`), "what goes with these
+ * colours" (`palette`), and "what moves from this colour to that one"
+ * (`gradient`). `mg.codes` and `mg.browse` set the precedent for a namespace
+ * when a capability is a family rather than a single verb.
  *
  * The namespace holds no transport of its own: the client hands it a bound
- * `get`, so auth, rate-limit accounting and error shaping stay in one place.
+ * `get`/`post`, so auth, rate-limit accounting and error shaping stay in one
+ * place.
  *
- * Both responses carry a `basis`. These are reads of a materialized view that is
- * refreshed on a schedule, not on write, so a caller can and should check how
- * much of the corpus the answer actually covers before treating it as complete.
+ * The two AGGREGATE responses carry a `basis`. Those are reads of a
+ * materialized view refreshed on a schedule, not on write, so a caller can and
+ * should check how much of the corpus the answer actually covers before
+ * treating it as complete. The two SEARCH responses are live and uncached.
  */
 import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsResponse } from "./colour-aggregate-types.js";
 import type { QueryParams } from "./http-transport.js";
 import type { SdkOperationId } from "./operations.js";
-/** The client's own request primitive, handed down so this file owns no transport. */
+import type { SearchGradientInput, SearchGradientResponse, SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
+/** The client's own request primitives, handed down so this file owns no transport. */
 export interface ColoursTransport {
     get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
+    post<T>(operationId: SdkOperationId, body: unknown, signal?: AbortSignal): Promise<T>;
 }
 export declare class ColoursClient {
     #private;
@@ -49,4 +54,42 @@ export declare class ColoursClient {
      * answer, listed rather than silently absent.
      */
     stats(signal?: AbortSignal): Promise<ColourStatsResponse>;
+    /**
+     * Find materials that go with a WHOLE PALETTE — N colours at once, not one
+     * colour repeated (POST `/api/v1/search/palettes`).
+     *
+     * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
+     * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
+     * swatch SHARE sits near the `proportion` you asked for. So the same colours
+     * at different proportions come back in a different order — a colour at 60%
+     * of the surface is a different query from one at 5%. `logic: "all"` (the
+     * default) applies a per-colour eligibility floor and returns the weighted
+     * geometric mean, so a candidate missing one colour is rejected rather than
+     * merely ranked low; `logic: "any"` is a noisy-OR that accepts partial
+     * answers but saturates once several colours score well, so prefer `all`
+     * when the ORDER is what matters.
+     *
+     * Every match carries the candidate's full `palette` plus a per-colour
+     * receipt naming the swatch that answered each queried colour.
+     *
+     * @example
+     * const { matches } = await mg.colours.palette({
+     *   colours: [
+     *     { hex: "F5EFE0", proportion: 0.6 },
+     *     { hex: "9CAF88", proportion: 0.2 },
+     *     { hex: "3E3B36", proportion: 0.2 },
+     *   ],
+     * });
+     */
+    palette(input: SearchPaletteInput, signal?: AbortSignal): Promise<SearchPaletteResponse>;
+    /**
+     * Find materials that move ALONG a colour transition — "cream to rust", in
+     * order (POST `/api/v1/search/gradients`).
+     *
+     * Not a palette: the score is multiplied by `coverage`, the share of the path
+     * the candidate actually spans, so a material owning only one end ranks below
+     * one that travels the whole way, and a flat single-colour material is
+     * rejected outright however close its hue sits to the path.
+     */
+    gradient(input: SearchGradientInput, signal?: AbortSignal): Promise<SearchGradientResponse>;
 }

package/colours-client.js

@@ -36,4 +36,46 @@ export class ColoursClient {
     stats(signal) {
         return this.#transport.get("get_colour_stats", undefined, signal);
     }
+    /**
+     * Find materials that go with a WHOLE PALETTE — N colours at once, not one
+     * colour repeated (POST `/api/v1/search/palettes`).
+     *
+     * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
+     * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
+     * swatch SHARE sits near the `proportion` you asked for. So the same colours
+     * at different proportions come back in a different order — a colour at 60%
+     * of the surface is a different query from one at 5%. `logic: "all"` (the
+     * default) applies a per-colour eligibility floor and returns the weighted
+     * geometric mean, so a candidate missing one colour is rejected rather than
+     * merely ranked low; `logic: "any"` is a noisy-OR that accepts partial
+     * answers but saturates once several colours score well, so prefer `all`
+     * when the ORDER is what matters.
+     *
+     * Every match carries the candidate's full `palette` plus a per-colour
+     * receipt naming the swatch that answered each queried colour.
+     *
+     * @example
+     * const { matches } = await mg.colours.palette({
+     *   colours: [
+     *     { hex: "F5EFE0", proportion: 0.6 },
+     *     { hex: "9CAF88", proportion: 0.2 },
+     *     { hex: "3E3B36", proportion: 0.2 },
+     *   ],
+     * });
+     */
+    palette(input, signal) {
+        return this.#transport.post("search_by_palette", input, signal);
+    }
+    /**
+     * Find materials that move ALONG a colour transition — "cream to rust", in
+     * order (POST `/api/v1/search/gradients`).
+     *
+     * Not a palette: the score is multiplied by `coverage`, the share of the path
+     * the candidate actually spans, so a material owning only one end ranks below
+     * one that travels the whole way, and a flat single-colour material is
+     * rejected outright however close its hue sits to the path.
+     */
+    gradient(input, signal) {
+        return this.#transport.post("search_by_gradient", input, signal);
+    }
 }

package/index.d.ts

@@ -21,6 +21,7 @@ export type * from "./codes-types.js";
 export { ColoursClient } from "./colours-client.js";
 export type { ColoursTransport } from "./colours-client.js";
 export type * from "./colour-aggregate-types.js";
+export type * from "./palette-search-types.js";
 export type * from "./brand-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";

package/material-asset-types.d.ts

@@ -1,6 +1,6 @@
 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 type MaterialAssetStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "failed" | "retired_placeholder">;
 export interface MaterialAssetProjectionImage {
     key: string;
     ordinal: number;

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.7.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 ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], 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/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
+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 ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"], 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 ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"], 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/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -26,6 +26,7 @@ const OPERATION_DEFINITIONS = [
     ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"],
     ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"],
     ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"],
+    ["suggest", "GET", "/api/v1/search/suggest", "search_suggest"],
     ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"],
     [
         "resolveAttributeValue",
@@ -39,7 +40,9 @@ const OPERATION_DEFINITIONS = [
     ["whoami", "GET", "/api/v1/whoami", "whoami"],
     ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"],
     ["demand", "GET", "/api/v1/demand", "get_material_demand"],
+    ["colours.palette", "POST", "/api/v1/search/palettes", "search_by_palette"],
     ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"],
+    ["colours.gradient", "POST", "/api/v1/search/gradients", "search_by_gradient"],
     ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"],
     [
         "attributeValues",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": {

package/palette-search-types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Wire types for MULTI-COLOUR search — `POST /api/v1/search/palettes` and
+ * `POST /api/v1/search/gradients`.
+ *
+ * Kept out of `types.ts` for the same reason `colour-aggregate-types.ts` and
+ * `codes-types.ts` are: the shared mirror is at its source-size budget. Same
+ * tolerant-parsing contract as the rest of the mirror — response enums are
+ * widened so a new server value still type-checks.
+ *
+ * The MATCH SEMANTICS these types carry are the server's, stated on
+ * {@link SearchPaletteInput.logic} and {@link GradientMatch.coverage} rather
+ * than left to the endpoint docs.
+ */
+import type { OklabTriple, OpenEnum } from "./types.js";
+/** How the per-colour scores are combined across a palette. */
+export type PaletteLogic = OpenEnum<"all" | "any">;
+/** One queried palette colour — exactly one of `hex` or `oklab`. */
+export interface PaletteQueryColour {
+    hex?: string;
+    oklab?: OklabTriple;
+    /**
+     * Share of the surface this colour should occupy, in (0,1]. Stating it
+     * CHANGES the ranking: a colour asked for at 0.6 rewards candidates whose own
+     * swatch sits near 0.6, not merely candidates that contain the colour.
+     */
+    proportion?: number;
+    /** Relative importance; defaults to 1 and is normalised across the query. */
+    weight?: number;
+}
+/** One gradient stop — exactly one of `hex` or `oklab`. Order is meaningful. */
+export interface GradientStop {
+    hex?: string;
+    oklab?: OklabTriple;
+}
+export interface SearchPaletteInput {
+    /** The palette to match, 1–8 colours. */
+    colours: PaletteQueryColour[];
+    /**
+     * `all` (the default) requires every queried colour to clear a per-colour
+     * eligibility floor and scores the weighted geometric mean; `any` is a
+     * noisy-OR and never rejects a candidate for missing one colour.
+     */
+    logic?: PaletteLogic;
+    /** Results to return; defaults to 24, capped at 48. */
+    limit?: number;
+}
+export interface SearchGradientInput {
+    /** The ordered colour transition, 2–6 stops. */
+    stops: GradientStop[];
+    /** Results to return; defaults to 24, capped at 48. */
+    limit?: number;
+}
+/** One swatch of a candidate's colorscope-extracted palette. */
+export interface CandidateSwatch {
+    hex: string;
+    proportion: number;
+    name: string | null;
+}
+/** Why a queried colour (or gradient sample) scored what it scored. */
+export interface ColourMatchReceipt {
+    queryHex: string;
+    /** `colourScore × proportionScore` for the best-matching swatch. */
+    score: number;
+    /** OKLab closeness alone, in [0,1]. */
+    colourScore: number;
+    /** Proportion agreement alone, in [0,1]. */
+    proportionScore: number;
+    /** The swatch that produced the score, or null when nothing matched. */
+    matched: CandidateSwatch | null;
+}
+/** Identity and evidence shared by both multi-colour match shapes. */
+export interface MultiColourMatchBase {
+    variantId: string;
+    brand: string;
+    product: string;
+    brandSlug: string | null;
+    productId: string | null;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    /** MB has retired or hidden this SKU. */
+    retired: boolean;
+    /** The candidate's full extracted palette — the evidence scored against. */
+    palette: CandidateSwatch[];
+    /** The aggregate match score in [0,1]; higher is closer. */
+    score: number;
+}
+export interface PaletteMatch extends MultiColourMatchBase {
+    /** One receipt per queried colour, in query order. */
+    colours: ColourMatchReceipt[];
+}
+export interface GradientMatch extends MultiColourMatchBase {
+    /**
+     * Distinct matched thirds of the path over 3. A material owning only one end
+     * of the transition caps out around 0.33 — coverage is what separates a real
+     * gradient match from a good match on a single stop.
+     */
+    coverage: number;
+    /** One receipt per sampled point along the path, in path order. */
+    samples: ColourMatchReceipt[];
+}
+export interface SearchPaletteResponse {
+    query: {
+        colours: Array<{
+            hex: string;
+            proportion?: number;
+            weight?: number;
+        }>;
+        logic: PaletteLogic;
+    };
+    count: number;
+    matches: PaletteMatch[];
+}
+export interface SearchGradientResponse {
+    query: {
+        stops: string[];
+        /** The sampled path points the search actually ran against. */
+        samples: string[];
+    };
+    count: number;
+    matches: GradientMatch[];
+}

package/palette-search-types.js

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

package/suggest-types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Entity typeahead (MG-654) — the hand-mirrored wire types for
+ * `GET /api/v1/search/suggest`, plus the one query-shaping rule the endpoint
+ * imposes.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
+ * `types.ts`, so importers see no difference.
+ */
+/** Which kind of entity a suggestion is — and therefore what `refId` means. */
+export type SuggestKind = "product" | "brand" | "category";
+/** How the query met the suggestion's label. Strongest first. */
+export type SuggestMatch = "prefix" | "word" | "contains" | "fuzzy";
+/** One ranked typeahead suggestion, carrying the identity it resolves to. */
+export interface Suggestion {
+    kind: SuggestKind;
+    /** The entity's name as written, for display. */
+    label: string;
+    /**
+     * The resolvable identity: a product id, a brand slug, or a product-type key.
+     * Selecting a suggestion should navigate to this, not re-search `label`.
+     */
+    refId: string;
+    match: SuggestMatch;
+    brandSlug: string | null;
+    brandName: string | null;
+    categoryKey: string | null;
+    /** A representative variant, so a client can open a material record directly. */
+    variantId: string | null;
+    variantCount: number;
+}
+/** The suggest response: the query as interpreted, plus the ranked suggestions. */
+export interface SuggestResponse {
+    /** The normalised query the corpus was matched against. */
+    query: string;
+    /** Ranked best-match-first. Empty when nothing came close — a miss, not an error. */
+    suggestions: Suggestion[];
+}
+/** Options for {@link MaterialGraphClient.suggest}. */
+export interface SuggestOptions {
+    /** How many suggestions to return (1–20, default 8). */
+    limit?: number;
+    /** Restrict to these kinds. Omit for all of them. */
+    kind?: SuggestKind | SuggestKind[];
+}
+/**
+ * Shape the query string for a suggest call.
+ *
+ * The only non-obvious rule: `kind` is a COMMA LIST on the wire (`product,brand`),
+ * which is the house convention for multi-value v1 params, so an array is joined
+ * here rather than being sent as repeated `?kind=` pairs the route would ignore.
+ * Undefined members are dropped by the transport.
+ */
+export declare function suggestQuery(q: string, options?: SuggestOptions): {
+    q: string;
+    limit?: number;
+    kind?: string;
+};

package/suggest-types.js

@@ -0,0 +1,21 @@
+/**
+ * Entity typeahead (MG-654) — the hand-mirrored wire types for
+ * `GET /api/v1/search/suggest`, plus the one query-shaping rule the endpoint
+ * imposes.
+ *
+ * Split out of `types.ts` for the repository's source-file size budget, the same
+ * reason `catalog-discovery-types.ts` sits beside it; both are re-exported from
+ * `types.ts`, so importers see no difference.
+ */
+/**
+ * Shape the query string for a suggest call.
+ *
+ * The only non-obvious rule: `kind` is a COMMA LIST on the wire (`product,brand`),
+ * which is the house convention for multi-value v1 params, so an array is joined
+ * here rather than being sent as repeated `?kind=` pairs the route would ignore.
+ * Undefined members are dropped by the transport.
+ */
+export function suggestQuery(q, options) {
+    const kind = Array.isArray(options?.kind) ? options.kind.join(",") : options?.kind;
+    return { q, limit: options?.limit, kind };
+}

package/types.d.ts

@@ -363,6 +363,7 @@ export interface ResolveAttributeResponse {
     candidates: AttributeCandidate[];
 }
 export type * from "./catalog-discovery-types.js";
+export type * from "./suggest-types.js";
 export type * from "./by-spec-types.js";
 export interface WhoamiResponse {
     principal: string;