@instruments/materialgraph 0.28.0 → 0.30.0

package/client.js

@@ -3,20 +3,17 @@ import { listBrands } from "./brands-client.js";
 import { CatalogueClient } from "./catalogue-client.js";
 import { CategoriesClient } from "./categories-client.js";
 import { DEFAULT_BASE_URL } from "./client-config.js";
-import { createSourceMaterialCommentsNamespace } from "./client-source-material-comments.js";
-import { listAttributes as listAttributesCall, resolveColour as resolveColourCall, suggest as suggestCall, suggestColour as suggestColourCall, } from "./client-vocabulary.js";
-import { CodesClient } from "./codes-client.js";
+import { listAttributes as listAttributesCall, listEnumValues as listEnumValuesCall, resolveColour as resolveColourCall, } from "./client-vocabulary.js";
 import { ColoursClient } from "./colours-client.js";
-import { coordinate as coordinateCall } from "./coordinate-client.js";
 import { MaterialGraphError } from "./errors.js";
 import { HttpTransport } from "./http-transport.js";
 import { matchStream as matchStreamCall } from "./match-stream.js";
-import { compositionReport as compositionReportCall } from "./material-composition-client.js";
 import { listVariantAssets as listVariantAssetsCall, materialBlocks as materialBlocksCall, materialDocuments as materialDocumentsCall, } from "./material-resources-client.js";
 // Aliased to `operation` — the local name every call site here already used.
 import { resolveOperation as operation } from "./operations.js";
-import { createRun, drainRunEvents, getRun, getSourceMaterialBatch as getSourceMaterialBatchCall, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { uploadSourceMaterial } from "./runs.js";
 import { SCHEMA_RESOURCE_OPERATION_IDS } from "./schema-resource-types.js";
+import { WorkflowsClient } from "./workflows-client.js";
 // Re-exported whole so `index.ts` and every existing importer keep their path.
 export * from "./client-config.js";
 /**
@@ -28,16 +25,15 @@ export * from "./client-config.js";
  * | The question | The lens |
  * | --- | --- |
  * | "find me something like this / matching these words" | {@link MaterialGraphClient.search} |
+ * | "tell me about THIS variant" | {@link MaterialGraphClient.getVariant} |
  * | "what's IN this photo?" | {@link MaterialGraphClient.match} / {@link MaterialGraphClient.matchStream} |
  * | "which materials, from anyone, meet this hard spec?" | {@link MaterialGraphClient.listVariants} |
- * | "what's near this colour / this palette / this gradient?" | {@link MaterialGraphClient.byColour}, `colours.palette()`, `colours.gradient()` |
- * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.listVariants} (same product, other colourways), {@link MaterialGraphClient.coordinate} |
+ * | "what's near this colour / this palette?" | {@link MaterialGraphClient.byColour}, `colours.palette()` |
+ * | "what goes with THIS material?" | {@link MaterialGraphClient.pairings}, {@link MaterialGraphClient.listVariants} (same product, other colourways) |
  * | "what does the manufacturer say is AVAILABLE on this?" | {@link MaterialGraphClient.associatedFinishes}, {@link MaterialGraphClient.associatedProducts} |
- * | "how much is this specified?" | {@link MaterialGraphClient.demand}, {@link MaterialGraphClient.demandBatch} |
- * | "is this allowed in an A-2 corridor?" | `codes.*` |
- * | "what can I even ask for?" | {@link MaterialGraphClient.specificationFacets}, `categories.list()` |
+ * | "what can I even ask for?" | {@link MaterialGraphClient.listVariantFacets}, `categories.list()` |
  * | "what is this word called here?" | {@link MaterialGraphClient.listAttributes} |
- * | "do the whole job for me, async" | {@link MaterialGraphClient.createRun} + `mg:compose` |
+ * | "do the whole job for me, async" | `workflows.start()` + `mg:compose` |
  *
  * Three structural rules that fall out of that table:
  * - **Colour is a separate lens.** {@link MaterialGraphClient.search} matches
@@ -71,35 +67,25 @@ export class MaterialGraphClient extends CatalogueClient {
      */
     categories;
     /**
-     * THE QUESTION: "is this material allowed HERE?" — a jurisdiction + occupancy +
-     * finish location, not a property of the material alone. `codes.context()`
-     * discovers the vocabulary, `codes.requirements()` states a space,
-     * `codes.advisory()` badges candidates.
-     *
-     * Instead use {@link MaterialGraphClient.listVariants} to find materials by a
-     * classification you already know you need; codes is what tells you WHICH one
-     * the space demands. ADVISORY ONLY: model code as adopted, never a
-     * determination for an authority having jurisdiction.
-     */
-    codes;
-    /**
-     * THE QUESTION: "what colours exist here?" (`profiles`, `stats`) and "what
-     * matches this whole SET of colours?" (`palette`, `gradient`).
+     * THE QUESTION: "what colours exist here?" and "what matches this whole SET
+     * of colours?" (`palette`).
      *
      * Instead use {@link MaterialGraphClient.byColour} for ONE colour and
      * {@link MaterialGraphClient.listVariants} to page through a colour's family.
      * Colour is usually derived from product imagery, which is visual likeness,
-     * not a colour specification. A maker's declared colour, such as a paint's
+     * not a colour specification. A brand's declared colour, such as a paint's
      * published hex, wins where MaterialGraph holds one, and each value's
      * source basis says which.
      */
     colours;
     /**
-     * THE QUESTION: "what did people say about this uploaded file, and record what
-     * they said." Names on these remarks are REPORTED, never verified — see
-     * {@link SourceMaterialCommentsNamespace}.
+     * THE QUESTION: "do a whole job for me" — the ASYNC lens. `start()` begins a
+     * Run of one registered workflow, `run()` polls it, `streamRunEvents()` and
+     * `drainRunEvents()` follow it live. Everything else on this client answers
+     * in one round trip; a Run may suspend for human input and finish minutes
+     * later. Replaces the flat `createRun()` / `run()` family, with no shim.
      */
-    sourceMaterialComments;
+    workflows;
     #transport;
     constructor(options) {
         if (!options.apiKey) {
@@ -116,15 +102,11 @@ export class MaterialGraphClient extends CatalogueClient {
         this.categories = new CategoriesClient({
             get: async (operationId, query, signal, pathParams) => await this.#get(operationId, query, signal, pathParams),
         });
-        this.codes = new CodesClient({
-            get: async (operationId, query, signal) => await this.#get(operationId, query, signal),
-            post: async (operationId, body, signal) => await this.#post(operationId, body, signal),
-        });
         this.colours = new ColoursClient({
             get: async (operationId, query, signal) => await this.#get(operationId, query, signal),
             post: async (operationId, body, signal) => await this.#post(operationId, body, signal),
         });
-        this.sourceMaterialComments = createSourceMaterialCommentsNamespace(this.#transport);
+        this.workflows = new WorkflowsClient({ transport });
     }
     get lastRateLimit() {
         return this.#transport.lastRateLimit;
@@ -200,7 +182,7 @@ export class MaterialGraphClient extends CatalogueClient {
      * palette), ranked by OKLab closeness to colour extracted from product imagery.
      *
      * Instead use `colours.palette()` for N colours at stated proportions (a
-     * different ranking, not a wrapper), `colours.gradient()` for a transition,
+     * different ranking, not a wrapper),
      * {@link MaterialGraphClient.resolveColour} first if you hold a NAME,
      * {@link MaterialGraphClient.listVariants} to page through a category or a brand, and
      * {@link MaterialGraphClient.search} when colour is one signal among many.
@@ -227,36 +209,33 @@ export class MaterialGraphClient extends CatalogueClient {
     }
     // ── Materials ──────────────────────────────────────────────────────────────
     /**
-     * THE QUESTION: "tell me everything about THIS material" (GET
-     * `/api/v1/materials/{variantId}`).
+     * THE QUESTION: "tell me about THIS variant" (GET
+     * `/api/v1/variants/{variantId}`, `get_variant`).
      *
      * The hinge of the API: every relationship lens
-     * ({@link MaterialGraphClient.listVariants}, {@link MaterialGraphClient.pairings},
-     * {@link MaterialGraphClient.demand}, `codes.advisory()`) hangs off a
-     * `variantId`. Instead use {@link MaterialGraphClient.listVariants} for many
-     * ids, or for the other colourways of the same product (MG-2222 retired
-     * this route's `?include=siblings`; ask `listVariants` with a `product in`
-     * filter instead), {@link MaterialGraphClient.materialBlocks} to tell "no
-     * value" from "not checked", {@link MaterialGraphClient.search} when you
-     * have no id yet.
+     * ({@link MaterialGraphClient.listVariants}, {@link MaterialGraphClient.pairings})
+     * hangs off a `variantId`. The answer is compact on purpose: name, code,
+     * product, brand, category, image and page. Name `attributes` and `blocks`
+     * to add their values under `specifications`; a null value is unknown, never
+     * false or zero. Instead use {@link MaterialGraphClient.listVariants} for many
+     * ids, or for the other colourways of the same product (ask `listVariants`
+     * with a `product in` filter),
+     * {@link MaterialGraphClient.materialBlocks} to tell "no value" from "not
+     * checked", {@link MaterialGraphClient.search} when you have no id yet.
      *
      * @param variantId Opaque — pass back exactly what you were given.
      */
-    async material(variantId, signal) {
-        return await this.#get("get_material", undefined, signal, { variantId });
+    async getVariant(variantId, options, signal) {
+        return await this.#get("get_variant", {
+            attributes: options?.attributes?.length
+                ? options.attributes.join(",")
+                : undefined,
+            blocks: options?.blocks?.length ? options.blocks.join(",") : undefined,
+        }, signal, { variantId });
     }
     async materialBlocks(variantId, signal) {
         return await materialBlocksCall(this.#transport, variantId, signal);
     }
-    /**
-     * THE QUESTION: "which product types can composition be answered for yet?"
-     *
-     * Coverage per product type, in Live SKUs as well as tuples. Read the SKU
-     * figure: one tuple can carry a hundred thousand SKUs or one.
-     */
-    async compositionReport(signal) {
-        return await compositionReportCall(this.#transport, signal);
-    }
     async listVariantAssets(variantId, options, signal) {
         return await listVariantAssetsCall(this.#transport, variantId, options, signal);
     }
@@ -266,7 +245,7 @@ export class MaterialGraphClient extends CatalogueClient {
     /**
      * THE QUESTION: "what does the schema DEFINE?" — the governed static registry.
      *
-     * Definitions, not data: use {@link MaterialGraphClient.specificationFacets} for
+     * Definitions, not data: use {@link MaterialGraphClient.listVariantFacets} for
      * what the corpus actually holds.
      */
     async schema(resource, signal) {
@@ -276,8 +255,7 @@ export class MaterialGraphClient extends CatalogueClient {
      * THE QUESTION: "what goes WITH this material?" — the companionship rail, hung
      * off one resolved material (GET `/api/v1/materials/{variantId}/pairings`).
      *
-     * Instead use {@link MaterialGraphClient.coordinate} for a whole palette of
-     * picks, {@link MaterialGraphClient.listVariants} for the same product in
+     * Instead use {@link MaterialGraphClient.listVariants} for the same product in
      * another colour, and `search({ similarTo })` for a LIKE-THIS substitute —
      * similar and complementary are opposite questions.
      *
@@ -310,10 +288,11 @@ export class MaterialGraphClient extends CatalogueClient {
      * of a product (`{terms: [{field: "product", op: "in", values:
      * [productId]}, {field: "variant", op: "not_in", values: [variantId]}]}` —
      * `filters` is kind-grouped, `{terms, numbers, presence}`, every condition
-     * across all three ANDed), or a category/maker listing. An explicit
+     * across all three ANDed), or a category/brand listing. An explicit
      * `variant in` id that does not resolve to an eligible variant is
-     * reported in `unresolvedVariantIds`, never silently dropped from the
-     * page.
+     * reported in `unresolvedVariantIds`, or in `excludedByCorpusScope` when
+     * it names a real variant outside the materials catalogue, never silently
+     * dropped from the page.
      *
      * `filters`/`optionalFilters`/`orderBy` are sent as URL-encoded JSON;
      * `attributes`/`include` as comma-separated lists — the server validates,
@@ -349,18 +328,35 @@ export class MaterialGraphClient extends CatalogueClient {
     async listVariantFacets(input, signal) {
         return await this.#post("list_variant_facets", input, signal);
     }
+    /**
+     * THE QUESTION: "which variants hold, resemble, or can be ranked by, this
+     * colour?" (POST `/api/v1/variants/by-colour`, MG-2217/MG-2230/MG-2247).
+     * One required `mode`: `contains` (a swatch for every required `colours[]`
+     * condition), `palette` (whole-palette closeness to `colours[]`, an
+     * image's extracted palette, or `targetVariantId`'s own palette) or
+     * `rerank` (reorder a held `variantIds` set by colour closeness). Use
+     * {@link MaterialGraphClient.byColour} instead for ONE colour against the
+     * search index rather than the canonical variant graph.
+     */
+    async findVariantsByColour(input, signal) {
+        return await this.#post("find_variants_by_colour", input, signal);
+    }
+    /**
+     * THE QUESTION: "what looks or feels like this?" (POST
+     * `/api/v1/variants/by-vector`, MG-2231). Eligible variants ranked by
+     * semantic or visual similarity to a text description (mood words count),
+     * an image reference, or both fused into one embedding. `filters` is the
+     * same tree {@link MaterialGraphClient.listVariants} takes. `query.mode`
+     * values other than `"text"` embed through Voyage and spend the shared
+     * per-key `embed` rate budget.
+     */
+    async findVariantsByVector(input, signal) {
+        return await this.#post("find_variants_by_vector", input, signal);
+    }
     /** Resolve a colour name to its hex, and the named paint's catalogue variant. */
     async resolveColour(name, signal, options) {
         return await resolveColourCall(this.#transport, name, signal, options);
     }
-    /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
-    async suggestColour(q, options, signal) {
-        return await suggestColourCall(this.#transport, q, options, signal);
-    }
-    /** Entity typeahead. Navigate using the selected `refId`; use `search()` for materials. */
-    async suggest(q, options, signal) {
-        return await suggestCall(this.#transport, q, options, signal);
-    }
     // ── Catalog ──────────────────────────────────────────────────────────────────
     /**
      * THE QUESTION: "which attribute means this phrase?" or "what could a
@@ -374,24 +370,28 @@ export class MaterialGraphClient extends CatalogueClient {
     async listAttributes(options, signal) {
         return await listAttributesCall(this.#transport, options, signal);
     }
+    /**
+     * THE QUESTION: "which value means this phrase?" or "what may this attribute
+     * be set to?" (GET `/api/v1/catalog/enum-values`). One page of a value
+     * dictionary's allowed values, browsed by `dictionaryId` (from a
+     * {@link MaterialGraphClient.listAttributes} item) or found by name, alias,
+     * misspelling or meaning across every dictionary. Pass an item's `valueId`
+     * with one of its `attributeIds` to {@link MaterialGraphClient.listVariants};
+     * an item with no `attributeIds` cannot be filtered on. Follow
+     * `pageInfo.endCursor` for the next page.
+     */
+    async listEnumValues(options, signal) {
+        return await listEnumValuesCall(this.#transport, options, signal);
+    }
     // Hard-specification search (formerly `bySpec()`, GET
     // `/api/v1/search/specifications`) moved to {@link MaterialGraphClient.listVariants}
     // (MG-2222): each `attribute:value` criterion is one `filters` condition —
     // `{field: attributeId, op: "in", values: [...]}` in `filters.terms` for a
     // term, `{field: attributeId, op: "gte"/"lte"/etc, value}` in
     // `filters.numbers` for a number — and every condition across the
-    // kind-grouped `filters` object must match. Use `codes.advisory()` when
-    // the real question is what a space demands, and {@link specificationFacets}
+    // kind-grouped `filters` object must match. See {@link listVariantFacets}
     // first if you do not know the canonical tokens.
     // ── Coverage + meta ──────────────────────────────────────────────────────────
-    /**
-     * Exact current primary-type status counts by retained source category path.
-     * `comparisonThreshold` is a reporting cutoff only: it never promotes a
-     * proposal into an accepted category.
-     */
-    async productTypeCoverage(options, signal) {
-        return await this.#get("get_product_type_status_coverage", options, signal);
-    }
     /**
      * THE QUESTION: "what is this key allowed to do?" Check `scopes` before
      * offering a capability: the write surfaces need `mg:ingest` / `mg:compose`,
@@ -400,66 +400,6 @@ export class MaterialGraphClient extends CatalogueClient {
     async whoami(signal) {
         return await this.#get("whoami", undefined, signal);
     }
-    // ── Pairings / demand ────────────────────────────────────────────────────────
-    /** What completes a scheme already part-chosen. See {@link coordinateCall}. */
-    async coordinate(input, signal) {
-        return await coordinateCall(this.#transport, input, signal);
-    }
-    /**
-     * THE QUESTION: "how much is this material actually specified, and what gets
-     * specified alongside it?" — real order behaviour, trailing 36 months.
-     *
-     * Instead use {@link MaterialGraphClient.demandBatch} for many ids (this one
-     * also resolves free text, which the batch deliberately does not) and
-     * {@link MaterialGraphClient.pairings} for a presentable rail. A null `demand`
-     * means UNREAD, never zero. Provide EXACTLY ONE of `variantId` or `material`.
-     */
-    async demand(params, signal) {
-        return await this.#get("get_material_demand", { material: params.material, variantId: params.variantId }, signal);
-    }
-    /**
-     * THE QUESTION: "for each of these picks I already hold, how much momentum does
-     * it have?" Enrichment, never discovery or ranking. Instead use
-     * {@link MaterialGraphClient.demand} for one material named in free text and
-     * {@link MaterialGraphClient.search} to find candidates at all. Only
-     * `state: "available"` carries numbers; the other three mean "no number", never
-     * "no demand".
-     *
-     * Enrich a bounded set of ALREADY-CHOSEN candidate ids with their real
-     * specification demand (POST `/api/v1/demand/batch`, 1–48 ids). The bounded
-     * batch complement to {@link demand}: no fuzzy resolution, ranking, or
-     * reordering — each id yields one discriminated `state` (`available` /
-     * `insufficient_data` / `no_signal` / `unknown_variant`) in input order and
-     * cardinality. This is the Desk's "show demand momentum for every pick in this
-     * scheme" read; an `mg:admin` key additionally sees per-result `evidence`.
-     *
-     * @example
-     * // Rank a shortlist by real specification momentum before locking the scheme.
-     * const { results } = await mg.demandBatch({
-     *   variantIds: scheme.picks.map((p) => p.variantId),
-     *   signal: "sampled",
-     *   context: { projectType: "hospitality" },
-     * });
-     * const rising = results.filter(
-     *   (r) => r.state === "available" && r.momentum.state === "rising",
-     * );
-     */
-    async demandBatch(input, signal) {
-        return await this.#post("get_demand_batch", input, signal);
-    }
-    // ── Codes (advisory building-code compliance) ────────────────────────────────
-    /**
-     * THE QUESTION: "may I put these materials in an A-2 corridor in Texas?"
-     *
-     * Badge materials against the advisory building-code registry (POST
-     * `/api/v1/codes/advisory`). Identical to {@link CodesClient.advisory}, kept
-     * flat because it shipped before the `codes` namespace existed — prefer
-     * `mg.codes.advisory()` in new code, and start at `mg.codes.context()` to
-     * discover every accepted context value. `unverified` is not a pass.
-     */
-    async codeAdvisory(input, signal) {
-        return await this.codes.advisory(input, signal);
-    }
     // ── Colour helpers (extract) ─────────────────────────────────────────────────
     /**
      * THE QUESTION: "what colours are in this image?" — the palette only, no
@@ -471,89 +411,23 @@ export class MaterialGraphClient extends CatalogueClient {
     async extractPalette(input, signal) {
         return await this.#post("extract_image_palette", input, signal);
     }
-    // ── Catalog (facets / glossary) ─────────────────────────────────────────────
-    /**
-     * THE QUESTION: "what can I even filter on, and what values does the corpus
-     * actually hold?" The start of every spec-driven workflow. Instead use
-     * {@link MaterialGraphClient.listAttributes} with `categoryIds` for what a
-     * product type COULD carry, {@link MaterialGraphClient.schema} for the definition.
-     *
-     * Discover the live specification vocabulary (GET
-     * `/api/v1/catalog/specifications/facets`) — the facetable spec attributes that
-     * have real product-graph data, each with its top canonical values and the
-     * variants/brands behind them. This is where a caller LEARNS that the data
-     * exists: LEED, GREENGUARD, ASTM E84 Class A, FloorScore, EPDs all surface here
-     * with counts. Includes the virtual `certification_programme` facet (its values
-     * are programme names). Learn an `attribute:value` here, then reuse it as a
-     * {@link MaterialGraphClient.listVariants} filter leaf or a {@link search}
-     * `filters` entry. NOTE: continuous
-     * numeric specs (e.g. `slip_resistance_dcof`, a 0–1 DCOF range) are NOT
-     * token-facetable and do not appear here — read those per-attribute.
-     */
-    async specificationFacets(signal) {
-        return await this.#get("list_spec_facets", undefined, signal);
-    }
     // ── Brands ───────────────────────────────────────────────────────────────────
     /** "Whose catalogs are in here, and how big is each?" — {@link listBrands}. */
     async brands(options = {}, signal) {
         return await listBrands(this.#transport, options, signal);
     }
-    // ── Runs (the hosted agentic surface) ────────────────────────────────────────
+    // ── Source material ──────────────────────────────────────────────────────────
     /**
      * Upload one atomic source-material batch (POST `/api/v1/source-material`,
      * multipart). Pass a heterogeneous pile via `{ files }` (any mix of PDF,
-     * text/markdown, and images — the server classifies each) or the legacy
-     * `{ brief, references }` shape. Requires the `mg:ingest` scope.
+     * text/markdown, and images — the server classifies each). Requires the
+     * `mg:source` scope, which a `source`, `ingest` or `admin` key carries.
      */
     async uploadSourceMaterial(input, signal) {
         return await uploadSourceMaterial(this.#transport, input, signal);
     }
-    /**
-     * Read back an uploaded batch (GET `/api/v1/source-material/{batchId}`): every
-     * file with a fetchable `url` and its analyses inlined. `analyses` is always
-     * an array — `[]` means nothing has been computed yet. Analyses are shared by
-     * content hash, so re-uploading an already-analysed image returns its analysis
-     * immediately. A batch you do not own raises the same 404 as one that does not
-     * exist. Requires the `mg:compose` scope.
-     */
-    async sourceMaterialBatch(batchId, signal) {
-        return await getSourceMaterialBatchCall(this.#transport, batchId, signal);
-    }
-    /**
-     * THE QUESTION: "do a whole job for me" — the ASYNC lens. Everything else here
-     * answers in one round trip; a Run may suspend for human input and finish
-     * minutes later. Follow with {@link MaterialGraphClient.streamRunEvents} (live)
-     * or {@link MaterialGraphClient.run} (poll). Pass `idempotencyKey` so a retry
-     * replays rather than duplicates.
-     */
-    async createRun(body, signal) {
-        return await createRun(this.#transport, body, signal);
-    }
-    /**
-     * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
-     * ledger record. Polling; prefer {@link MaterialGraphClient.streamRunEvents}
-     * when a human is waiting.
-     */
-    async run(runId, signal) {
-        return await getRun(this.#transport, runId, signal);
-    }
     /** Follow a verdict cell's citation handle to its canonical claim source. */
     async citation(citationId, signal) {
         return await this.#get("get_verdict_citation", undefined, signal, { citationId });
     }
-    /**
-     * Stream ordered Run events as an async iterator (GET
-     * `/api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or the
-     * signal aborts; pass `after` to resume from the last observed sequence.
-     */
-    streamRunEvents(runId, options) {
-        return streamRunEvents(this.#transport, runId, options);
-    }
-    /**
-     * Collect Run events until a terminal event, the deadline, or the stream ends
-     * — the bounded events-log pattern (a single pass over {@link streamRunEvents}).
-     */
-    async drainRunEvents(runId, options) {
-        return await drainRunEvents(this.#transport, runId, options);
-    }
 }

package/colour-region-types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A colour word's region in OKLCh: what a name like "sage" covers, rather than
+ * one point. A swatch counts inside it, so it is a box (lightness, chroma, hue)
+ * and not a distance. Search echoes it on the plan's colour and accepts it back
+ * on the request's `colour`, and the colour lookups carry it on each resolved
+ * region.
+ */
+export type ColourRegionRange = {
+    /** Inclusive OKLab lightness bounds, 0 to 1. */
+    lightness: [number, number];
+    /** Inclusive OKLCh chroma bounds. */
+    chroma: [number, number];
+    /**
+     * The hue arc in degrees, 0 to 360, inclusive. It wraps when its start is past
+     * its end (reds). `null` means any hue, which is what a neutral is.
+     */
+    hue: [number, number] | null;
+};

package/colours-client.d.ts

@@ -1,28 +1,21 @@
-import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsParams, ColourStatsResponse } from "./colour-aggregate-types.js";
 import type { QueryParams } from "./http-transport.js";
 import type { SdkOperationId } from "./operations.js";
 /**
- * The colour surface, namespaced as `mg.colours` — the aggregate reads
- * (`stats`, `profiles`) plus MULTI-COLOUR search (`palette`, `gradient`).
+ * The colour surface, namespaced as `mg.colours` — MULTI-COLOUR search
+ * (`palette`).
  *
- * 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` sets the precedent for a namespace when a
- * capability is a family rather than a single verb.
+ * A namespace rather than a flat method on an already-large client facade:
+ * "what goes with these colours" (`palette`). `mg.codes` 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`/`post`, so auth, rate-limit accounting and error shaping stay in one
  * place.
  *
- * 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.
+ * `palette`'s response is live and uncached.
  *
- * ROUTING OUT OF THIS NAMESPACE. Colour is a lens, and these are not the only
- * doors into it:
+ * ROUTING OUT OF THIS NAMESPACE. Colour is a lens, and this is not the only
+ * door into it:
  * - ONE colour → `mg.byColour({ hex })`. This namespace's `palette` is for N
  *   colours at stated proportions, which is a different ranking, not a
  *   convenience wrapper.
@@ -35,7 +28,7 @@ import type { SdkOperationId } from "./operations.js";
  * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
  * likeness, never a stated colour specification.
  */
-import type { SearchGradientInput, SearchGradientResponse, SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
+import type { SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
 /** The client's own request primitives, handed down so this file owns no transport. */
 export type ColoursTransport = {
     get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
@@ -44,64 +37,11 @@ export type ColoursTransport = {
 export declare class ColoursClient {
     #private;
     constructor(transport: ColoursTransport);
-    /**
-     * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
-     * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).
-     *
-     * An aggregate over a category, not a list of materials: use `mg.byColour()` or
-     * `mg.search()` when you want the materials themselves, and
-     * {@link ColoursClient.stats} for coverage across the whole corpus rather than
-     * one category's palette. Check `basis` — this reads a scheduled materialized
-     * view, so it can lag the catalog.
-     *
-     * `groupBy: "group"` takes product-type GROUP keys and merges every leaf type
-     * under a group into one histogram BEFORE ranking — a group's palette, not the
-     * union of its leaves' heads. `select: "diverse"` returns visually spread
-     * swatches (greedy max-min over OKLab, 0.02 minimum separation, backfilled by
-     * frequency if fewer survive) instead of the most frequent ones; a client
-     * cannot recover that spread from a truncated frequency list, which is why it
-     * is a server mode rather than a local sort.
-     *
-     * `groupBy: "merged"` merges across the KEYS as well and returns ONE profile
-     * over the union of their leaves — the palette of a caller-defined facet such
-     * as "Wood" (`wood_surface` + `wood_flooring`) that the taxonomy holds no
-     * single node for, and that no combination of per-key responses reconstructs.
-     * Its keys may sit at either tier, `categoryKey` is those keys sorted and
-     * joined with `+`, and `members` hands them back so nothing has to split it.
-     *
-     * A selected category with no colour data comes back as a zero-count profile,
-     * not a missing key.
-     */
-    profiles(params: ColourProfilesParams, signal?: AbortSignal): Promise<CategoryColourProfilesResponse>;
-    /**
-     * THE QUESTION: "how much colour does the graph hold AT ALL?" — corpus-level
-     * coverage, before you trust any colour answer.
-     *
-     * The sanity check under every other colour call. Use
-     * {@link ColoursClient.profiles} for one category's palette and
-     * `mg.colourFacets()` for the vocabulary. `basis.omissions` lists what this
-     * call deliberately does not answer — read it rather than assuming silence.
-     *
-     * Corpus colour coverage (GET `/api/v1/colours/stats`): how much of the graph
-     * carries colour at all, the split across the canonical colour families, and
-     * coverage per product-type group. `basis` states the source and freshness of
-     * each section plus `basis.omissions` — what this call deliberately does not
-     * answer, listed rather than silently absent.
-     *
-     * Pass `{ groupBy: "brand,category" }` for the whole brand x category x
-     * family matrix in one call, or a `brandSlug`/`categoryKey` scope for a slice
-     * of it — either way it arrives as `rows`, each row carrying `brandId` and
-     * `brandSlug` to join on. Without any of those parameters the payload is the
-     * platform-wide one and `rows` is absent. `families` is never scoped by them.
-     */
-    stats(params?: ColourStatsParams, signal?: AbortSignal): Promise<ColourStatsResponse>;
     /**
      * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at
      * stated proportions, not one colour repeated (POST `/api/v1/search/palettes`).
      *
-     * Use `mg.byColour()` for a single colour, {@link ColoursClient.gradient} when
-     * the colours form an ordered TRANSITION rather than a set, and
-     * `mg.coordinate()` when the scheme is made of materials rather than colours.
+     * Use `mg.byColour()` for a single colour.
      *
      * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
      * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
@@ -127,17 +67,4 @@ export declare class ColoursClient {
      * });
      */
     palette(input: SearchPaletteInput, signal?: AbortSignal): Promise<SearchPaletteResponse>;
-    /**
-     * THE QUESTION: "what moves from this colour to that one?" — materials that
-     * travel ALONG a transition, in order (POST `/api/v1/search/gradients`).
-     *
-     * Order is the whole point: use {@link ColoursClient.palette} when the colours
-     * are a set rather than a path, and `mg.byColour()` for a single colour.
-     *
-     * 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>;
 }