@instruments/materialgraph 0.1.0 → 0.2.0

package/spec-types.js

@@ -0,0 +1,40 @@
+/**
+ * The specification surface — the typed vocabulary for asking a material
+ * "does it meet this spec?": certifications (GREENGUARD, FloorScore, Declare),
+ * VOC / emissions testing (CDPH v1.2), sustainability programmes (LEED, EPDs),
+ * and fire / abrasion / slip classifications.
+ *
+ * Every shape here is a hand-authored, zero-dependency mirror of the server's
+ * spec filter contract (`specFilterSchema` in
+ * `@materialgraph/products/search/schema`). It exists so a caller answering a
+ * question like "find me a GREENGUARD-certified alternative" or "the same fire
+ * class, but with an EPD on record" reaches for a NAMED, typed criterion instead
+ * of hand-assembling a magic `attribute:value` string.
+ *
+ * These criteria drive two operations equally:
+ * - `client.search({ filters: [...] })` — spec gates layered onto a ranked
+ *   (colour / visual / lexical) search.
+ * - `client.bySpec(...)` — the value-anchored, spec-only primitive, which takes
+ *   the same criteria as `attribute:value` strings (build them with the helpers
+ *   in `./specifications`).
+ */
+/**
+ * The virtual attribute id that matches a certification PROGRAMME wherever it
+ * landed at ingest.
+ *
+ * Certifications are not stored under one attribute: each record is an object
+ * (`{ programme, name, status, … }`) split across FOUR real object-array
+ * attributes by intent — general `certifications`,
+ * `sustainability_certifications`, `material_health_certifications`, and
+ * `voc_emissions_testing_certificate` (GREENGUARD Gold / FloorScore / CDPH land
+ * in the last). A caller shouldn't have to know which bucket a programme fell
+ * into, so this single virtual id matches the `programme` term across all four.
+ *
+ * @example
+ * // "find a GREENGUARD-certified alternative"
+ * client.search({
+ *   similarTo: { variantId: seed },
+ *   filters: [{ attributeId: CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, term: "GREENGUARD Gold" }],
+ * });
+ */
+export const CERTIFICATION_PROGRAMME_ATTRIBUTE_ID = "certification_programme";

package/specifications.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Zero-dependency builders for the specification surface. Turn a plain-language
+ * spec intent into a typed criterion the SDK's two spec operations accept:
+ *
+ * - `search({ filters })` takes {@link SpecFilter} objects — a spec gate layered
+ *   onto a ranked (colour / visual / lexical) search. Build them with
+ *   {@link specTerm}, {@link hasSpec}, and {@link certificationProgramme}.
+ * - `bySpec(specs)` takes `attribute:value` strings — the value-anchored,
+ *   spec-only primitive. Build them with {@link specCriterion} and
+ *   {@link certificationProgrammeCriterion}.
+ *
+ * The point of these helpers: Desk (and any spec-driven caller) never has to
+ * remember that a certification programme lives under a VIRTUAL attribute, nor
+ * hand-format the `attribute:value` string the `bySpec` route splits on its
+ * first `:`.
+ */
+import { type CertificationProgrammeFilter, type SpecPresenceFilter, type SpecTermFilter } from "./spec-types.js";
+/**
+ * A term-equality criterion for `search({ filters })` — the attribute must
+ * carry this canonical value.
+ *
+ * @example
+ * // "same fire class as the seed"
+ * client.search({ similarTo: { variantId }, filters: [specTerm("fire_classifications", "astm_e84_class_a")] });
+ */
+export declare function specTerm(attributeId: string, term: string): SpecTermFilter;
+/**
+ * A presence criterion for `search({ filters })` — the attribute must have ANY
+ * accepted value.
+ *
+ * @example
+ * // "…and it must have an EPD on record"
+ * client.search({ similarTo: { variantId }, filters: [hasSpec("environmental_product_declaration")] });
+ */
+export declare function hasSpec(attributeId: string): SpecPresenceFilter;
+/**
+ * A certification-programme criterion for `search({ filters })`, pinned to the
+ * virtual attribute so a programme matches wherever it landed at ingest
+ * (compliance / sustainability / material-health / VOC buckets).
+ *
+ * @example
+ * // "find a GREENGUARD-certified alternative"
+ * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("GREENGUARD Gold")] });
+ */
+export declare function certificationProgramme(programme: string): CertificationProgrammeFilter;
+/**
+ * An `attribute:value` criterion string for `bySpec`. The `bySpec` route splits
+ * on the FIRST `:`, so a value may itself contain colons; the attribute id may
+ * not.
+ *
+ * @example
+ * client.bySpec([specCriterion("primary_material", "textile"), specCriterion("fire_classifications", "astm_e84_class_a")]);
+ */
+export declare function specCriterion(attributeId: string, value: string): string;
+/**
+ * An `attribute:value` criterion string for `bySpec` that filters by
+ * certification PROGRAMME across all four certification buckets.
+ *
+ * @example
+ * // every brand's GREENGUARD-Gold materials
+ * client.bySpec([certificationProgrammeCriterion("GREENGUARD Gold")]);
+ */
+export declare function certificationProgrammeCriterion(programme: string): string;

package/specifications.js

@@ -0,0 +1,73 @@
+/**
+ * Zero-dependency builders for the specification surface. Turn a plain-language
+ * spec intent into a typed criterion the SDK's two spec operations accept:
+ *
+ * - `search({ filters })` takes {@link SpecFilter} objects — a spec gate layered
+ *   onto a ranked (colour / visual / lexical) search. Build them with
+ *   {@link specTerm}, {@link hasSpec}, and {@link certificationProgramme}.
+ * - `bySpec(specs)` takes `attribute:value` strings — the value-anchored,
+ *   spec-only primitive. Build them with {@link specCriterion} and
+ *   {@link certificationProgrammeCriterion}.
+ *
+ * The point of these helpers: Desk (and any spec-driven caller) never has to
+ * remember that a certification programme lives under a VIRTUAL attribute, nor
+ * hand-format the `attribute:value` string the `bySpec` route splits on its
+ * first `:`.
+ */
+import { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, } from "./spec-types.js";
+/**
+ * A term-equality criterion for `search({ filters })` — the attribute must
+ * carry this canonical value.
+ *
+ * @example
+ * // "same fire class as the seed"
+ * client.search({ similarTo: { variantId }, filters: [specTerm("fire_classifications", "astm_e84_class_a")] });
+ */
+export function specTerm(attributeId, term) {
+    return { attributeId, term };
+}
+/**
+ * A presence criterion for `search({ filters })` — the attribute must have ANY
+ * accepted value.
+ *
+ * @example
+ * // "…and it must have an EPD on record"
+ * client.search({ similarTo: { variantId }, filters: [hasSpec("environmental_product_declaration")] });
+ */
+export function hasSpec(attributeId) {
+    return { attributeId, hasValue: true };
+}
+/**
+ * A certification-programme criterion for `search({ filters })`, pinned to the
+ * virtual attribute so a programme matches wherever it landed at ingest
+ * (compliance / sustainability / material-health / VOC buckets).
+ *
+ * @example
+ * // "find a GREENGUARD-certified alternative"
+ * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("GREENGUARD Gold")] });
+ */
+export function certificationProgramme(programme) {
+    return { attributeId: CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, term: programme };
+}
+/**
+ * An `attribute:value` criterion string for `bySpec`. The `bySpec` route splits
+ * on the FIRST `:`, so a value may itself contain colons; the attribute id may
+ * not.
+ *
+ * @example
+ * client.bySpec([specCriterion("primary_material", "textile"), specCriterion("fire_classifications", "astm_e84_class_a")]);
+ */
+export function specCriterion(attributeId, value) {
+    return `${attributeId}:${value}`;
+}
+/**
+ * An `attribute:value` criterion string for `bySpec` that filters by
+ * certification PROGRAMME across all four certification buckets.
+ *
+ * @example
+ * // every brand's GREENGUARD-Gold materials
+ * client.bySpec([certificationProgrammeCriterion("GREENGUARD Gold")]);
+ */
+export function certificationProgrammeCriterion(programme) {
+    return specCriterion(CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, programme);
+}

package/sse.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A minimal, dependency-free Server-Sent Events reader — the primitive behind
+ * {@link MaterialGraphClient.streamRunEvents}. Hand-rolled (no `eventsource`,
+ * no `undici`) so the SDK stays zero-runtime-dep and works unchanged inside
+ * Node route handlers, where `fetch` yields a byte `ReadableStream`.
+ *
+ * The parser follows the WHATWG event-stream tokenizer closely enough for the
+ * `/api/v1/runs/{runId}/events` contract: `\n`, `\r\n`, and `\r` line endings,
+ * multi-line `data:` accumulation, comment (`:`-prefixed) lines, and a single
+ * optional leading space after the field colon. Frames split across network
+ * chunks are held in an internal buffer until their terminating blank line.
+ */
+/** One dispatched SSE frame. `data` is the joined data lines (no trailing newline). */
+export interface SseFrame {
+    id?: string;
+    event?: string;
+    data: string;
+}
+/**
+ * A push-based SSE line assembler. Feed it decoded text with {@link push}; it
+ * returns any frames completed by that text. Call {@link flush} once the stream
+ * ends to dispatch a final frame that had data but no terminating blank line.
+ */
+export declare class SseDecoder {
+    #private;
+    push(text: string): SseFrame[];
+    /** Dispatch a trailing frame that had fields but no closing blank line. */
+    flush(): SseFrame[];
+}
+/**
+ * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
+ * or `signal` aborts (mid-read abort rejections are swallowed once the signal
+ * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
+ */
+export declare function readSseFrames(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<SseFrame, void, unknown>;

package/sse.js

@@ -0,0 +1,147 @@
+/**
+ * A minimal, dependency-free Server-Sent Events reader — the primitive behind
+ * {@link MaterialGraphClient.streamRunEvents}. Hand-rolled (no `eventsource`,
+ * no `undici`) so the SDK stays zero-runtime-dep and works unchanged inside
+ * Node route handlers, where `fetch` yields a byte `ReadableStream`.
+ *
+ * The parser follows the WHATWG event-stream tokenizer closely enough for the
+ * `/api/v1/runs/{runId}/events` contract: `\n`, `\r\n`, and `\r` line endings,
+ * multi-line `data:` accumulation, comment (`:`-prefixed) lines, and a single
+ * optional leading space after the field colon. Frames split across network
+ * chunks are held in an internal buffer until their terminating blank line.
+ */
+/**
+ * A push-based SSE line assembler. Feed it decoded text with {@link push}; it
+ * returns any frames completed by that text. Call {@link flush} once the stream
+ * ends to dispatch a final frame that had data but no terminating blank line.
+ */
+export class SseDecoder {
+    #buffer = "";
+    #dataLines = [];
+    #id;
+    #event;
+    #hasFields = false;
+    push(text) {
+        this.#buffer += text;
+        const frames = [];
+        for (;;) {
+            const lineEnd = this.#nextLineEnd();
+            if (lineEnd === null)
+                break;
+            const line = this.#buffer.slice(0, lineEnd.index);
+            this.#buffer = this.#buffer.slice(lineEnd.nextIndex);
+            const frame = this.#consumeLine(line);
+            if (frame)
+                frames.push(frame);
+        }
+        return frames;
+    }
+    /** Dispatch a trailing frame that had fields but no closing blank line. */
+    flush() {
+        if (this.#buffer.length > 0) {
+            // At end of stream a deferred trailing CR is a real terminator, not data.
+            const line = this.#buffer.endsWith("\r") ? this.#buffer.slice(0, -1) : this.#buffer;
+            this.#buffer = "";
+            const frame = this.#consumeLine(line);
+            if (frame)
+                return [frame];
+        }
+        const frame = this.#dispatch();
+        return frame ? [frame] : [];
+    }
+    /** Locate the next line terminator, deferring a lone trailing `\r` (may be `\r\n`). */
+    #nextLineEnd() {
+        for (let i = 0; i < this.#buffer.length; i += 1) {
+            const char = this.#buffer[i];
+            if (char === "\n")
+                return { index: i, nextIndex: i + 1 };
+            if (char === "\r") {
+                if (i === this.#buffer.length - 1)
+                    return null;
+                return this.#buffer[i + 1] === "\n"
+                    ? { index: i, nextIndex: i + 2 }
+                    : { index: i, nextIndex: i + 1 };
+            }
+        }
+        return null;
+    }
+    #consumeLine(line) {
+        if (line.length === 0)
+            return this.#dispatch();
+        if (line.startsWith(":"))
+            return undefined;
+        const colon = line.indexOf(":");
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? "" : line.slice(colon + 1);
+        if (value.startsWith(" "))
+            value = value.slice(1);
+        if (field === "data") {
+            this.#dataLines.push(value);
+            this.#hasFields = true;
+        }
+        else if (field === "event") {
+            this.#event = value;
+            this.#hasFields = true;
+        }
+        else if (field === "id") {
+            this.#id = value;
+            this.#hasFields = true;
+        }
+        return undefined;
+    }
+    #dispatch() {
+        if (!this.#hasFields)
+            return undefined;
+        const frame = { data: this.#dataLines.join("\n") };
+        if (this.#event !== undefined)
+            frame.event = this.#event;
+        if (this.#id !== undefined)
+            frame.id = this.#id;
+        this.#dataLines = [];
+        this.#event = undefined;
+        this.#id = undefined;
+        this.#hasFields = false;
+        return frame;
+    }
+}
+/**
+ * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
+ * or `signal` aborts (mid-read abort rejections are swallowed once the signal
+ * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
+ */
+export async function* readSseFrames(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const sse = new SseDecoder();
+    try {
+        for (;;) {
+            if (signal?.aborted)
+                return;
+            let result;
+            try {
+                result = await reader.read();
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return;
+                throw error;
+            }
+            if (result.done) {
+                for (const frame of sse.push(decoder.decode()))
+                    yield frame;
+                for (const frame of sse.flush())
+                    yield frame;
+                return;
+            }
+            const text = decoder.decode(result.value, { stream: true });
+            for (const frame of sse.push(text)) {
+                if (signal?.aborted)
+                    return;
+                yield frame;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/types.d.ts

@@ -134,6 +134,32 @@ export interface SearchResultItem {
     siblingCount?: number;
     visualMeanings?: VisualMeaning[];
 }
+/** The lean `view:"card"` result item — identity + name + thumbnail + score. */
+export interface SearchCardItem {
+    variantId: string;
+    productId: string | null;
+    brandSlug: string | null;
+    brand: string;
+    /** Product name (the full item's `product`). */
+    name: string;
+    variantName: string | null;
+    imageUrl: string | null;
+    score: number;
+}
+/**
+ * A feed total with its honesty basis. `exact` — the true count (≤ the cap of
+ * 1,000, or a facet-MV read). `lowerBound` — a floor (cap hit, ANN-pool bound,
+ * or a degraded count). Never a silent approximation.
+ */
+export interface CountedTotal {
+    value: number;
+    basis: OpenEnum<"exact" | "lowerBound">;
+}
+/** Feed counts — present under `count:true` or `collapse:"product"`. */
+export interface SearchCounts {
+    variants: CountedTotal;
+    products?: CountedTotal;
+}
 /** The single candidate source a query resolved to. */
 export type SearchMode = OpenEnum<"image" | "colour" | "text" | "lexical">;
 /** Rerank-term report (absent in colour mode — there colour IS the source). */
@@ -142,16 +168,22 @@ export interface SearchRerankReport {
     colourWeight?: number;
     colourLabel?: string;
 }
-/** The full search response (both GET and POST forms return this envelope). */
+/**
+ * The search response envelope. `view` discriminates the `results` union:
+ * `"full"` (default) carries {@link SearchResultItem}s, `"card"` the lean
+ * {@link SearchCardItem}s. Every other field is shared. `counts` is present
+ * under `count:true` or `collapse:"product"` (replacing the former
+ * `variantCount`/`productCount`).
+ */
 export interface SearchResponse {
+    view: OpenEnum<"full" | "card">;
     results: SearchResultItem[];
     suggestions: SearchSuggestion[];
     mode: SearchMode;
     maxScore: number;
     cursor?: string;
     rerank?: SearchRerankReport;
-    variantCount?: number;
-    productCount?: number;
+    counts?: SearchCounts;
     note?: string;
     timings?: Record<string, number>;
     /** Echo of the resolved query input (raw image bytes/vector are never echoed). */
@@ -159,6 +191,11 @@ export interface SearchResponse {
     /** A `getVariantBrief` echo of the seed variant, present only in `variantId` seed mode. */
     seed?: MaterialTile | Record<string, unknown>;
 }
+/** The `view:"card"` response form — the lean grid projection of {@link SearchResponse}. */
+export interface SearchCardResponse extends Omit<SearchResponse, "view" | "results"> {
+    view: OpenEnum<"card">;
+    results: SearchCardItem[];
+}
 /** An inferred product-type category from the query image, with its boost. */
 export interface MatchCategoryInference {
     productTypeId: string;
@@ -437,6 +474,12 @@ export interface SearchInput {
     cursor?: string;
     explain?: boolean;
     collapse?: OpenEnum<"none" | "product">;
+    /** Opt-in feed total: EXACT up to 1,000, `lowerBound` beyond / for ANN pools. */
+    count?: boolean;
+    /** Only return materials with at least one catalog image. Default false (full catalog). */
+    hasImages?: boolean;
+    /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
+    view?: OpenEnum<"full" | "card">;
 }
 /** Query-string params for the GET `/search` form. */
 export interface SearchGetParams {
@@ -450,6 +493,12 @@ export interface SearchGetParams {
     limit?: number;
     /** "0" or "1" — include per-signal `signals` on each result. */
     explain?: OpenEnum<"0" | "1">;
+    /** "true" — opt in to a `counts.variants` feed total. */
+    count?: OpenEnum<"true">;
+    /** "true" — only return materials with at least one catalog image. */
+    hasImages?: OpenEnum<"true">;
+    /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
+    view?: OpenEnum<"full" | "card">;
 }
 /** Params for `search/colours`. */
 export interface ByColourParams {
@@ -559,6 +608,98 @@ export interface DemandResponse {
     demand: MaterialDemandResult;
     cospec: CoSpecifiedResult;
 }
+/** Which behavioural signal candidate demand is read from. */
+export type DemandSignal = OpenEnum<"sampled" | "considered" | "specified">;
+/**
+ * Body for `POST /api/v1/demand/batch` — enrich 1–48 already-selected candidate
+ * ids with their real specification demand, in input order and cardinality.
+ */
+export interface DemandBatchInput {
+    /** 1–48 canonical variant ids. Order AND cardinality are preserved — duplicates are echoed, never collapsed. */
+    variantIds: string[];
+    /** The behavioural signal to read demand from. Defaults to `sampled` (order co-occurrence) server-side. */
+    signal?: DemandSignal;
+    /** Optional declared context (e.g. `{ projectType: "hospitality" }`) — echoed for provenance, never used to rank or filter. */
+    context?: Record<string, string>;
+}
+/** Headline population behind the metric — this variant's own counts. */
+export interface DemandBatchPopulation {
+    specCount: number;
+    projectCount: number;
+    customerCount: number;
+}
+/** The consideration→specification funnel (project-grain; `exclusionRate` is annotate-only). */
+export interface DemandBatchFunnel {
+    consideredProjects: number;
+    specifiedProjects: number;
+    excludedCount: number;
+    exclusionRate: number;
+}
+/** Per-result guardrail status — present on `internal` (`mg:admin`) results only. */
+export interface DemandBatchEvidence {
+    belowPrivacyFloor: boolean;
+    belowQualityFloor: boolean;
+    suppressedForPublic: boolean;
+}
+/** A variant that carries a usable demand signal. */
+export interface DemandBatchAvailableResult {
+    variantId: string;
+    state: "available";
+    population: DemandBatchPopulation;
+    /** Exact per-quarter counts (sparse — zero-spec quarters are absent). */
+    intervals: DemandQuarter[];
+    momentum: DemandMomentum;
+    /** The funnel; null when the signal is not `sampled` or no `considered` row/session exists. */
+    funnel: DemandBatchFunnel | null;
+    /** Exact guardrail evidence for `internal` callers; null for public. */
+    evidence: DemandBatchEvidence | null;
+}
+/** A variant with a stats row that is below the public quality floor. */
+export interface DemandBatchInsufficientResult {
+    variantId: string;
+    state: "insufficient_data";
+}
+/** A variant with no stats — indistinguishable from a privacy-suppressed one for public callers. */
+export interface DemandBatchNoSignalResult {
+    variantId: string;
+    state: "no_signal";
+}
+/** A requested id that resolves to no real variant. */
+export interface DemandBatchUnknownResult {
+    variantId: string;
+    state: "unknown_variant";
+}
+/** One discriminated result per input id, in input order and cardinality. */
+export type DemandBatchResult = DemandBatchAvailableResult | DemandBatchInsufficientResult | DemandBatchNoSignalResult | DemandBatchUnknownResult;
+/** The `POST /api/v1/demand/batch` envelope. */
+export interface DemandBatchResponse {
+    /** The completed ingestion-session id these counts were mined in (the dataset generation). */
+    generationId: string;
+    metric: "specification_demand";
+    /** The metric universe — the window and signal the counts are scoped to. */
+    universe: {
+        window: "trailing_36mo";
+        signal: DemandSignal;
+        description: string;
+    };
+    /** The guardrail status under which `results` were projected. */
+    guardrail: {
+        audience: OpenEnum<"public" | "internal">;
+        minProjectCount: number;
+        minCustomerCount: number;
+    };
+    /** Outcome tallies over `results` — never a denominator for the metric. */
+    coverage: {
+        requested: number;
+        available: number;
+        insufficientData: number;
+        noSignal: number;
+        unknownVariant: number;
+    };
+    /** The echoed declared context, or null when none was supplied. */
+    context: Record<string, string> | null;
+    results: DemandBatchResult[];
+}
 export interface CoordinateSeed extends DemandSeed {
     /** The input reference this seed resolved from. */
     resolvedFrom: string;
@@ -742,7 +883,7 @@ export interface ExtractPaletteInput {
 /** Options for a cacheable GET batch read (`materialsCached`). */
 export interface MaterialsBatchGetOptions extends MaterialsBatchOptions {
 }
-/** Options for `brands/{slug}`. */
+/** Options for `brands/{brandSlug}`. */
 export interface BrandOptions {
     /** Alternate fuzzy query; takes precedence over the path slug when present. */
     q?: string;