@instruments/materialgraph 0.3.0 → 0.4.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,9 +53,7 @@ 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),
@@ -173,25 +173,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 +186,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/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 ["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"]];
 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",

package/package.json

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

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;