@instruments/materialgraph 0.35.0 → 0.36.0

package/search-variants-types.d.ts

@@ -1,3 +1,4 @@
+import type { FindVariantsByVectorItem } from "./find-variants-by-vector-types.js";
 /**
  * @module search-variants-types
  * @description Hand-maintained mirror of `search_variants`'s (MG-2223) input
@@ -9,6 +10,16 @@
  */
 import type { ColorRangeCondition, FilterGroups, ListVariantsInclude, ListVariantsOutput, OptionalFilterGroups } from "./list-variants-types.js";
 import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
+/** Found by meaning, because fewer than half the query's words were understood. Follows `items`; not filtered by its words. */
+export type SearchVariantsMeaning = {
+    /** Why no meaning results came back. */
+    error?: "timed_out" | "unavailable";
+    items: FindVariantsByVectorItem[];
+    /** How many of the query's content words were understood. */
+    understoodWords: number;
+    /** How many content words the query has. */
+    words: number;
+};
 /** Switches one of a previous answer's `choices`: its `handle`, and the `group` and `id` of the alternative to read it as. */
 export type SearchVariantsSelection = {
     group: string;
@@ -72,6 +83,8 @@ export type SearchVariantsOutput = ListVariantsOutput & {
         correction: string;
         word: string;
     }[];
+    /** Results found by meaning, present only when most words were not understood. */
+    meaning?: SearchVariantsMeaning;
     /** The `listVariants()` filters that ran: send them, with `optionalFilters` and `name`, to `listVariants()` to narrow or widen this search. */
     filters?: FilterGroups;
     /** The paint name looked up, as `listVariants()` takes it. */

package/types.d.ts

@@ -102,7 +102,7 @@ export type CospecPairing = {
      * How this companion relates to the seed — the distinction raw order evidence
      * does not carry, and the one that decides what you may claim.
      *
-     * - `companion` — a DIFFERENT BRAND entirely. This is the cross-brand claim
+     * - `other_brand` — a DIFFERENT BRAND entirely. This is the cross-brand claim
      *   the rail exists to make.
      * - `brand_sibling` — the seed's own brand, a different product.
      * - `colorway` — the seed's own product, restyled.
@@ -113,7 +113,7 @@ export type CospecPairing = {
      * Optional because responses captured before the field existed are genuinely
      * in the wild; absent means "from an older version", never "unrelated".
      */
-    relation?: "companion" | "brand_sibling" | "colorway";
+    relation?: "other_brand" | "brand_sibling" | "colorway";
     category: string | null;
     projectCount: number;
     customerCount: number;

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();
-    }
-}