@instruments/materialgraph 0.33.0 → 0.36.0

package/colours-client.d.ts

@@ -1,70 +0,0 @@
-import type { QueryParams } from "./http-transport.js";
-import type { SdkOperationId } from "./operations.js";
-/**
- * The colour surface, namespaced as `mg.colours` — MULTI-COLOUR search
- * (`palette`).
- *
- * 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.
- *
- * `palette`'s response is live and uncached.
- *
- * 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.
- * - A colour NAME rather than a hex → `mg.resolveColour(name)` first.
- * - Colour WORDS (families, moods, undertones) → `mg.colourFacets()`.
- * - Walking the corpus by lightness/vividness → `mg.listVariants({ orderBy })`.
- * - Colour as one signal among words and a seed → `mg.search(...)`.
- *
- * And the honesty rule the whole lens rests on: every colour here is DERIVED
- * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
- * likeness, never a stated colour specification.
- */
-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>;
-    post<T>(operationId: SdkOperationId, body: unknown, signal?: AbortSignal): Promise<T>;
-};
-export declare class ColoursClient {
-    #private;
-    constructor(transport: ColoursTransport);
-    /**
-     * 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.
-     *
-     * 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>;
-}

package/colours-client.js

@@ -1,38 +0,0 @@
-export class ColoursClient {
-    #transport;
-    constructor(transport) {
-        this.#transport = transport;
-    }
-    /**
-     * 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.
-     *
-     * 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 },
-     *   ],
-     * });
-     */
-    async palette(input, signal) {
-        return await this.#transport.post("search_by_palette", input, signal);
-    }
-}

package/find-companions-types.d.ts

@@ -1,70 +0,0 @@
-/**
- * @module find-companions-types
- * @description Hand-maintained mirror of `find_companions`' (MG-2332) input and
- * output wire shapes. The source of truth is
- * `packages/products/src/cospec/schema.ts` (`findCompanionsInputSchema`,
- * `findCompanionsResultSchema`). This SDK has no RUNTIME dependency on
- * `@materialgraph/products` (it's a devDependency only, for the parity tests in
- * `__tests__/`), so the shapes are copied here rather than imported.
- * `contract-parity.test.ts` keeps this mirror honest against the server types,
- * the project-type list included.
- */
-/** The closed sector vocabulary co-specification evidence is tagged with. */
-export type CompanionProjectType = "Workplace" | "Residential" | "Institution Education" | "Hospitality: Hotel" | "Mixed-Use & Multi-Unit Residential" | "Healthcare" | "Hospitality: Restaurant" | "Government" | "Senior Living" | "Retail" | "Other" | "Sports Entertainment" | "Wellness" | "Medical Dental" | "Aviation" | "Industrial" | "Tech" | "Transportation" | "Single Family" | "Condominium Cooperative" | "Marine" | "Power & Energy" | "University Design Program: Interior Design" | "Non-Billable" | "University Design Program: Interior Architecture" | "University Design Program: Architecture" | "Historic Preservation";
-/** At least one of `variantIds` and `materials`, at most twelve together. */
-export type FindCompanionsInput = {
-    /** Optional row fields: image adds imageUrl, colour adds swatches. */
-    include?: ("image" | "colour")[];
-    /** Ops and audit switch: leave sample cards in. Default false. */
-    includeSamplingArtifacts?: boolean;
-    /** Companions to return, default 20, at most 100. */
-    limit?: number;
-    /** Names to resolve when you hold no ids. Misses come back unresolved. */
-    materials?: string[];
-    /** Only companions sampled together in projects of this sector. */
-    projectType?: CompanionProjectType;
-    /** Variants to find companions for. */
-    variantIds?: string[];
-};
-export type FindCompanionsRow = {
-    brand: string;
-    /** Palette likeness to the seeds. Present with `include: ["colour"]`; never reorders. */
-    colourFit?: number | null;
-    /** Present with `include: ["image"]`. */
-    imageUrl?: string | null;
-    /** Mean lift over the seeds it pairs with; above 1 is above average. */
-    lift: number;
-    product: string;
-    /** Why it was suggested, in one line. */
-    reason: string;
-    /** `companion` is another brand; `brand_sibling` and `colourway` share the seed's. */
-    relation: "companion" | "brand_sibling" | "colourway";
-    /** How many seeds it was sampled with. */
-    seedMatchCount: number;
-    /** Present with `include: ["colour"]`. */
-    swatches?: {
-        hex: string;
-        proportion: number;
-    }[];
-    variantId: string;
-    variantName: string | null;
-};
-export type FindCompanionsOutput = {
-    /** Strongest first: seeds matched, then summed lift, one row per product. */
-    companions: FindCompanionsRow[];
-    /** The seeds as resolved, so a caller sees what a name became. */
-    seeds: {
-        brand: string;
-        /** Present with `include: ["image"]`. */
-        imageUrl?: string | null;
-        product: string;
-        /** The id or name this seed came from. */
-        resolvedFrom: string;
-        variantId: string;
-        variantName: string | null;
-    }[];
-    /** Seed ids outside the materials catalogue; present only when at least one was. */
-    excludedByCorpusScope?: string[];
-    /** References that matched no variant. */
-    unresolved: string[];
-};

package/material-query-plan-types.d.ts

@@ -1,70 +0,0 @@
-/** Hand-mirrored wire types for `POST /api/v1/search/plan`. */
-import type { OpenEnum } from "./types.js";
-/** One wanted value: hard filters the page, soft only orders it. */
-export type MaterialQueryWant = {
-    attributeId: string;
-    terms: string[];
-    phrase: string;
-    strength: OpenEnum<"hard" | "soft">;
-    fill: number;
-};
-export type MaterialQueryExclusion = {
-    attributeId: string;
-    term: string;
-    phrase: string;
-};
-/** The dictionary reading of one query, as the index search runs it. */
-export type MaterialQueryReading = {
-    normalised: string;
-    category: {
-        productTypeIds: string[];
-        label: string;
-        phrase: string;
-    } | null;
-    brands: {
-        ids: string[];
-        names: string[];
-        phrase: string;
-    } | null;
-    wants: MaterialQueryWant[];
-    excludes: MaterialQueryExclusion[];
-    excludeBrands: string[];
-    colour: {
-        phrase: string;
-        familyId: string;
-        hex: string;
-        oklab: [number, number, number];
-        family12: string[];
-    } | null;
-    vendorColourNames: string[];
-    leftover: string[];
-    softAlone: boolean;
-};
-/** Present when a word no material carries was corrected: showing results for `to`. */
-export type MaterialQueryCorrection = {
-    from: string;
-    to: string;
-    words: {
-        word: string;
-        correction: string;
-    }[];
-};
-/** One search over the index. */
-export type MaterialSearchRequest = {
-    text: string;
-    view?: OpenEnum<"card" | "full">;
-    limit?: number;
-    cursor?: string;
-};
-export type MaterialQueryPlan = {
-    version: OpenEnum<"2">;
-    rawQuery: string;
-    normalisedQuery: string;
-    readingVersion: string;
-    source: OpenEnum<"dictionary" | "jev">;
-    cached: boolean;
-    plan: MaterialQueryReading;
-    correction: MaterialQueryCorrection | null;
-    /** The one search to run, in the phrasing that was read. */
-    requests: MaterialSearchRequest[];
-};

package/material-query-plan-types.js

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

package/ndjson.d.ts

@@ -1,46 +0,0 @@
-/**
- * A minimal, dependency-free NDJSON (newline-delimited JSON) line reader — the
- * primitive for line-oriented JSON streams. Hand-rolled so the
- * SDK stays zero-runtime-dep and works unchanged inside Node route handlers,
- * where `fetch` yields a byte `ReadableStream`.
- *
- * Deliberately a SIBLING of `sse.ts`, not a reuse of it. NDJSON and SSE agree on
- * nothing but "text arrives in chunks": SSE frames are `field: value` lines
- * terminated by a BLANK line, with comment lines and multi-line `data:`
- * accumulation, whereas an NDJSON frame is exactly one line of JSON. Feeding
- * NDJSON through the SSE tokenizer would read `{"type":"step",…}` as a field
- * named `{"type"` and silently discard every frame. The two also want OPPOSITE
- * end-of-stream policies: SSE dispatches a trailing partial frame as valid,
- * while a truncated NDJSON line must surface as an error (enforced by the
- * caller, which parses whatever `flush` returns rather than dropping it).
- *
- * Line endings: the reader splits on `\n` only, per the NDJSON contract. A `\r`
- * left by a CRLF-normalising proxy stays as trailing whitespace on the line,
- * which `JSON.parse` ignores.
- */
-/**
- * A push-based NDJSON line assembler. Feed it decoded text with {@link push};
- * it returns the lines that text COMPLETED, terminators removed. Any partial
- * trailing line is held in an internal buffer until a later chunk terminates it,
- * or until {@link flush} surrenders it at end of stream.
- */
-export declare class NdjsonDecoder {
-    #private;
-    /** Absorb one decoded chunk and return the lines it completed, in order. */
-    push(text: string): string[];
-    /**
-     * Surrender the unterminated remainder at end of stream — a well-formed
-     * NDJSON stream's final line need not carry a trailing newline. The remainder
-     * is RETURNED, never dropped: a truncated frame is the caller's error to
-     * raise, not this decoder's fragment to discard.
-     */
-    flush(): string[];
-}
-/**
- * Iterate the NDJSON lines of a byte stream. Only lines with non-whitespace
- * content are yielded — a blank separator line carries no frame and must never
- * reach `JSON.parse`, where it would become an empty object. Stops cleanly when
- * the stream ends or `signal` aborts (mid-read abort rejections are swallowed
- * once the signal is set).
- */
-export declare function readNdjsonLines(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<string, void, unknown>;

package/ndjson.js

@@ -1,111 +0,0 @@
-/**
- * A minimal, dependency-free NDJSON (newline-delimited JSON) line reader — the
- * primitive for line-oriented JSON streams. Hand-rolled so the
- * SDK stays zero-runtime-dep and works unchanged inside Node route handlers,
- * where `fetch` yields a byte `ReadableStream`.
- *
- * Deliberately a SIBLING of `sse.ts`, not a reuse of it. NDJSON and SSE agree on
- * nothing but "text arrives in chunks": SSE frames are `field: value` lines
- * terminated by a BLANK line, with comment lines and multi-line `data:`
- * accumulation, whereas an NDJSON frame is exactly one line of JSON. Feeding
- * NDJSON through the SSE tokenizer would read `{"type":"step",…}` as a field
- * named `{"type"` and silently discard every frame. The two also want OPPOSITE
- * end-of-stream policies: SSE dispatches a trailing partial frame as valid,
- * while a truncated NDJSON line must surface as an error (enforced by the
- * caller, which parses whatever `flush` returns rather than dropping it).
- *
- * Line endings: the reader splits on `\n` only, per the NDJSON contract. A `\r`
- * left by a CRLF-normalising proxy stays as trailing whitespace on the line,
- * which `JSON.parse` ignores.
- */
-/**
- * A push-based NDJSON line assembler. Feed it decoded text with {@link push};
- * it returns the lines that text COMPLETED, terminators removed. Any partial
- * trailing line is held in an internal buffer until a later chunk terminates it,
- * or until {@link flush} surrenders it at end of stream.
- */
-export class NdjsonDecoder {
-    #buffer = "";
-    /** Absorb one decoded chunk and return the lines it completed, in order. */
-    push(text) {
-        this.#buffer += text;
-        const lines = [];
-        for (;;) {
-            const index = this.#buffer.indexOf("\n");
-            if (index === -1) {
-                break;
-            }
-            lines.push(this.#buffer.slice(0, index));
-            this.#buffer = this.#buffer.slice(index + 1);
-        }
-        return lines;
-    }
-    /**
-     * Surrender the unterminated remainder at end of stream — a well-formed
-     * NDJSON stream's final line need not carry a trailing newline. The remainder
-     * is RETURNED, never dropped: a truncated frame is the caller's error to
-     * raise, not this decoder's fragment to discard.
-     */
-    flush() {
-        if (this.#buffer.length === 0) {
-            return [];
-        }
-        const remainder = this.#buffer;
-        this.#buffer = "";
-        return [remainder];
-    }
-}
-/**
- * Iterate the NDJSON lines of a byte stream. Only lines with non-whitespace
- * content are yielded — a blank separator line carries no frame and must never
- * reach `JSON.parse`, where it would become an empty object. Stops cleanly when
- * the stream ends or `signal` aborts (mid-read abort rejections are swallowed
- * once the signal is set).
- */
-export async function* readNdjsonLines(body, signal) {
-    const reader = body.getReader();
-    const decoder = new TextDecoder();
-    const ndjson = new NdjsonDecoder();
-    try {
-        for (;;) {
-            if (signal?.aborted) {
-                return;
-            }
-            let result;
-            try {
-                result = await reader.read();
-            }
-            catch (error) {
-                if (signal?.aborted) {
-                    return;
-                }
-                throw error;
-            }
-            if (result.done) {
-                // `decode()` with no argument flushes any dangling multi-byte sequence.
-                for (const line of ndjson.push(decoder.decode())) {
-                    if (line.trim().length > 0) {
-                        yield line;
-                    }
-                }
-                for (const line of ndjson.flush()) {
-                    if (line.trim().length > 0) {
-                        yield line;
-                    }
-                }
-                return;
-            }
-            for (const line of ndjson.push(decoder.decode(result.value, { stream: true }))) {
-                if (signal?.aborted) {
-                    return;
-                }
-                if (line.trim().length > 0) {
-                    yield line;
-                }
-            }
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-}

package/palette-search-types.d.ts

@@ -1,171 +0,0 @@
-import type { ColourCategoryGate } from "./by-colour-types.js";
-import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
-/**
- * Wire types for MULTI-COLOUR search — `POST /api/v1/search/palettes`.
- *
- * Kept out of `types.ts` for the repository's source-file 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} rather than left to the endpoint docs.
- */
-import type { VariantId } from "./identifiers.js";
-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 type PaletteQueryColour = {
-    hex?: string;
-    oklab?: OklabTriple;
-    /**
-     * Share of the surface this colour should occupy, in (0,1]. A colour stated
-     * below 5% is dropped; otherwise not applied, since a palette is ordered by
-     * its first colour alone.
-     */
-    proportion?: number;
-    /** Relative importance. Not applied: a palette is ordered by its first colour. */
-    weight?: number;
-};
-export type SearchPaletteInput = {
-    /**
-     * HARD category filter: category-group or product-type names or keys.
-     * Absent, the page holds surface materials only, so lights, taps and
-     * furniture are left out.
-     */
-    category?: string[];
-    corpusScope?: CorpusScope;
-    /**
-     * The palette to match, 1–8 colours. The page is ordered by the FIRST colour;
-     * the rest come back in `query.droppedColours`.
-     */
-    colours: PaletteQueryColour[];
-    /**
-     * Kept so existing callers still parse: the one search orders the page by
-     * the first colour with no eligibility floor, so `all` and `any` return the
-     * same page.
-     */
-    logic?: PaletteLogic;
-    /** Results to return; defaults to 24, capped at 48. */
-    limit?: number;
-};
-/**
- * One swatch used for scoring. Samplize paint uses its selected published hex;
- * other materials use colorscope palettes extracted from imagery. `name` is null when no human
- * name was resolved — unnamed, not colourless.
- */
-export type CandidateSwatch = {
-    hex: string;
-    proportion: number;
-    name: string | null;
-};
-/** Why a queried colour (or gradient sample) scored what it scored. */
-export type ColourMatchReceipt = {
-    queryHex: string;
-    /** `colourScore × proportionScore`, so `colourScore` on the one search. */
-    score: number;
-    /**
-     * Closeness in [0,1] of the matched swatch to the queried colour, from plain
-     * OKLab distance with lightness counted in full. Not a confidence.
-     */
-    colourScore: number;
-    /** Proportion agreement; always 1, since no proportion is applied. */
-    proportionScore: number;
-    /** The swatch that produced the score, or null when nothing matched. */
-    matched: CandidateSwatch | null;
-    /**
-     * Whether `matched` has a hue compatible with the queried colour, at the
-     * response's `hueGate` thresholds. A flag, never a gate: an incompatible
-     * swatch still scores and ranks. Absent when there is no `matched` swatch.
-     */
-    hueCompatible?: boolean;
-};
-/** Identity and evidence shared by both multi-colour match shapes. */
-export type MultiColourMatchBase = {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    brandSlug: string | null;
-    productId: string | null;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    /**
-     * SHA-256 of the displayed image `imageUrl` points at, as a hex digest.
-     * ABSENT means no hash is on record, never that there is no image.
-     */
-    imageSha256?: string;
-    /** MB has retired or hidden this SKU. */
-    retired: boolean;
-    /**
-     * The catalog GROUP — "Flooring", "Textile Materials", "Coatings" — or null
-     * when the material has no accepted primary product type.
-     *
-     * A palette query is cross-category BY INTENT: a designer building a scheme,
-     * not browsing one aisle. So this is the field that says whether a result
-     * answers the question — one real palette returned 30 of 40 results in a
-     * single category while every one of the fourteen groups held something
-     * closer on the same colours (MG-1245). Group by it, and keep null as its own
-     * bucket: null means UNKNOWN, not uncategorised, and it is not rare.
-     */
-    category: string | null;
-    /** The candidate's full extracted palette — the evidence scored against. */
-    palette: CandidateSwatch[];
-    /**
-     * Closeness in [0,1] of the material's own colour to the searched colour,
-     * the page's order. Not a confidence or a percentage.
-     */
-    score: number;
-};
-export type PaletteMatch = {
-    /** One receipt per queried colour, in query order. */
-    colours: ColourMatchReceipt[];
-} & MultiColourMatchBase;
-/**
- * The thresholds behind every receipt's `hueCompatible`: the exact values
- * passed to colorscope's `isHueCompatible`, fixed server-side with no request
- * knob. A FLAG, never admission or ranking: every swatch still scores, and the
- * page and its order are the same with or without it.
- */
-export type HueGateReceipt = {
-    /** Below this query chroma the colour is achromatic and any hue is admitted. */
-    achromaticQueryChroma: number;
-    /** A swatch must carry at least this share of the query colour's chroma. */
-    minChromaRatio: number;
-    /** Floor on the cosine agreement between the two hue vectors. */
-    minHueCosine: number;
-};
-/**
- * A PAGE, NOT A CORPUS. `count` is `matches.length` under `limit` (24 default,
- * 48 max) — this surface states no corpus total and has no cursor, so "N
- * materials match this palette" is not a claim you can make from it.
- */
-export type SearchPaletteResponse = {
-    corpusScope?: CorpusScopeReceipt;
-    /** The query as interpreted — check it before trusting a surprising order. */
-    query: {
-        /** Colours that actually ran after minor stated shares were omitted. */
-        colours: {
-            hex: string;
-            proportion?: number;
-            weight?: number;
-        }[];
-        /** Colours not searched because their stated share was below 5%. */
-        droppedColours: {
-            hex: string;
-            proportion?: number;
-            weight?: number;
-        }[];
-        logic: PaletteLogic;
-        /** `no_effective_colours` means no material query ran. */
-        outcome: OpenEnum<"matches" | "no_effective_colours">;
-    };
-    /** The category gate the page ran under. */
-    categoryGate?: ColourCategoryGate;
-    /** The thresholds behind each receipt's `hueCompatible`. Absent only on responses stored before it existed. */
-    hueGate?: HueGateReceipt;
-    /** `matches.length`, capped by `limit`. Never a corpus total. */
-    count: number;
-    matches: PaletteMatch[];
-};

package/palette-search-types.js

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