@instruments/materialgraph 0.32.0 → 0.35.0

package/spec-types.d.ts

@@ -1,109 +0,0 @@
-/**
- * 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, and choosing between them IS the
- * routing decision:
- * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
- *   (colour / visual / lexical) search. Reach for it when relevance still
- *   matters: "something like this seed, but Class A".
- * - `client.listVariants({ filters })` — the value-anchored, SPEC-ONLY
- *   primitive, which takes a `{field: attributeId, op, ...}` filter leaf
- *   (build one term with the helpers in `./specifications`, or a plain
- *   object literal for anything else). Reach for it when the spec is the
- *   whole question and ranking would be noise.
- *
- * Discover the tokens before you spend them: `client.listVariantFacets()` for
- * the live values of the attributes you name, `client.attributeValues()` for one attribute's
- * values, `client.listAttributes({ query })` to turn a phrase into a canonical
- * attribute id. A hand-guessed token returns an honest empty answer, which is
- * the hardest kind of bug to see.
- */
-/**
- * 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.
- *
- * The `term` may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
- * server-side to its canonical programme token, or a canonical token directly
- * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
- *
- * @example
- * // "find a GREENGUARD-certified alternative"
- * client.search({
- *   similarTo: { variantId: seed },
- *   filters: [{ attributeId: CERTIFICATION_PROGRAMME_ATTRIBUTE_ID, term: "GREENGUARD Gold" }],
- * });
- */
-export declare const CERTIFICATION_PROGRAMME_ATTRIBUTE_ID = "certification_programme";
-/** The literal type of {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID}. */
-export type CertificationProgrammeAttributeId = typeof CERTIFICATION_PROGRAMME_ATTRIBUTE_ID;
-/**
- * A term-equality spec criterion: the attribute must carry this canonical value,
- * e.g. `{ attributeId: "fire_classifications", term: "astm_e84_class_a" }`.
- * Discover valid `attributeId`/`term` pairs via `client.listVariantFacets()`
- * and `client.listEnumValues()`, or find an attribute from free text with
- * `client.listAttributes({ query })`.
- */
-export type SpecTermFilter = {
-    attributeId: string;
-    term: string;
-};
-/**
- * A negative spec criterion. `whenUnstated` (absent = `"drop"`) controls what an
- * UNKNOWN effective value does: `"drop"` requires a known value, so a variant
- * that never states the attribute does not pass; `"pass"` admits it — a variant
- * only fails by STATING the excluded term.
- */
-export type SpecExclusionFilter = {
-    attributeId: string;
-    excludesTerm: string;
-    whenUnstated?: "drop" | "pass";
-};
-/**
- * A presence spec criterion: the attribute must have ANY accepted value —
- * "has an EPD on record", "has a measured slip figure at all". Not supported for
- * {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID} (a programme is matched by name,
- * never by bare presence).
- */
-export type SpecPresenceFilter = {
-    attributeId: string;
-    hasValue: true;
-}
-/** Date-sensitive presence is currently executable only for EPD expiration. */
- | {
-    attributeId: "epd_expiration_date";
-    hasValue: true;
-    asOf: string;
-};
-/**
- * A certification-programme criterion — a {@link SpecTermFilter} pinned to the
- * virtual {@link CERTIFICATION_PROGRAMME_ATTRIBUTE_ID}. Structurally assignable
- * to {@link SpecFilter}, so it drops straight into `search({ filters })`.
- */
-export type CertificationProgrammeFilter = {
-    attributeId: CertificationProgrammeAttributeId;
-    term: string;
-};
-/**
- * A hard, canonical-attribute spec criterion — either a term match or a
- * presence check. The union the search engine applies as a restriction BEFORE
- * ranking. Identical in shape to the SDK's `SearchFilter`.
- */
-export type SpecFilter = SpecTermFilter | SpecExclusionFilter | SpecPresenceFilter;

package/spec-types.js

@@ -1,54 +0,0 @@
-/**
- * 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, and choosing between them IS the
- * routing decision:
- * - `client.search({ filters: [...] })` — spec gates layered onto a RANKED
- *   (colour / visual / lexical) search. Reach for it when relevance still
- *   matters: "something like this seed, but Class A".
- * - `client.listVariants({ filters })` — the value-anchored, SPEC-ONLY
- *   primitive, which takes a `{field: attributeId, op, ...}` filter leaf
- *   (build one term with the helpers in `./specifications`, or a plain
- *   object literal for anything else). Reach for it when the spec is the
- *   whole question and ranking would be noise.
- *
- * Discover the tokens before you spend them: `client.listVariantFacets()` for
- * the live values of the attributes you name, `client.attributeValues()` for one attribute's
- * values, `client.listAttributes({ query })` to turn a phrase into a canonical
- * attribute id. A hand-guessed token returns an honest empty answer, which is
- * the hardest kind of bug to see.
- */
-/**
- * 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.
- *
- * The `term` may be a display name or alias ("GREENGUARD Gold", "LEED"), resolved
- * server-side to its canonical programme token, or a canonical token directly
- * (e.g. `greenguard_certificate`, `has_greenguard_gold_certification`).
- *
- * @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

@@ -1,34 +0,0 @@
-import type { CertificationProgrammeFilter, SpecPresenceFilter, 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 const 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 const 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).
- *
- * The value is a canonical programme token (e.g. `greenguard_certificate`,
- * `has_greenguard_gold_certification`). The one search matches tokens on its
- * index and does not resolve display names, so a name such as
- * "GREENGUARD Gold" is a 400 naming the term.
- *
- * @example
- * // "find a GREENGUARD-certified alternative"
- * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("has_greenguard_gold_certification")] });
- */
-export declare const certificationProgramme: (programme: string) => CertificationProgrammeFilter;

package/specifications.js

@@ -1,56 +0,0 @@
-/**
- * Zero-dependency builders for the specification surface. Turn a
- * plain-language spec intent into a typed {@link SpecFilter} `search({
- * filters })` accepts: hard token sets on the one search's index, run in the
- * same query. Build them with {@link specTerm}, {@link hasSpec}, and
- * {@link certificationProgramme}.
- *
- * The point of these helpers: Desk (and any spec-driven caller) never has to
- * remember that a certification programme lives under a VIRTUAL attribute.
- *
- * A hard specification across every brand (formerly `bySpec`, built with
- * `specCriterion`/`specRangeCriterion`) is now `list_variants`'s `filters`:
- * `{field: attributeId, op: "in", values: [...]}` for a term,
- * `{field: attributeId, op: "gte"/"lte"/etc, value}` for a number — a plain
- * object literal needs no encoder (MG-2222).
- */
-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 const specTerm = (attributeId, term) => ({ 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 const hasSpec = (attributeId) => ({
-    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).
- *
- * The value is a canonical programme token (e.g. `greenguard_certificate`,
- * `has_greenguard_gold_certification`). The one search matches tokens on its
- * index and does not resolve display names, so a name such as
- * "GREENGUARD Gold" is a 400 naming the term.
- *
- * @example
- * // "find a GREENGUARD-certified alternative"
- * client.search({ similarTo: { variantId: seed }, filters: [certificationProgramme("has_greenguard_gold_certification")] });
- */
-export const certificationProgramme = (programme) => ({
-    attributeId: CERTIFICATION_PROGRAMME_ATTRIBUTE_ID,
-    term: programme,
-});

package/validation.d.ts

@@ -1,43 +0,0 @@
-/**
- * The SDK's shared wire-validation primitives — the vocabulary every hand-rolled
- * mirror of a canonical Zod schema is built from.
- *
- * The SDK publishes with ZERO runtime dependencies, so it cannot call
- * `schema.parse()` on anything. Where a wire payload must be proven rather than
- * trusted, it is checked with these helpers and the result is pinned against the
- * real schema in `contract-parity.test.ts`. Each helper mirrors one Zod
- * construct, named for it, so a reviewer can read the mirror against the schema
- * line by line.
- *
- * Every helper takes the same three shapes: the value, a `what` path used in the
- * diagnostic (`results[3].verdict.cells[0].state`), and a {@link ValidationFailure}
- * owned by the calling module — so one payload's failures all read alike without
- * this file knowing what a Match frame or a Run event is.
- */
-import type { MaterialGraphError } from "./errors.js";
-/**
- * Builds the one error a validation run raises. The calling module supplies it,
- * so the message names that payload and quotes its source.
- */
-export type ValidationFailure = (reason: string) => MaterialGraphError;
-/** A `z.object({…})`. */
-export declare const requireRecord: (value: unknown, what: string, fail: ValidationFailure) => Record<string, unknown>;
-/** A `z.string()`. */
-export declare const requireString: (value: unknown, what: string, fail: ValidationFailure) => string;
-/** A `z.string().optional()`: absent is fine, present-but-wrong is not. */
-export declare const requireOptionalString: (value: unknown, what: string, fail: ValidationFailure) => void;
-/** A `z.string().nullable()`. */
-export declare const requireNullableString: (value: unknown, what: string, fail: ValidationFailure) => string | null;
-/** A `z.boolean()`. */
-export declare const requireBoolean: (value: unknown, what: string, fail: ValidationFailure) => boolean;
-/** A `z.boolean().optional()`. */
-export declare const requireOptionalBoolean: (value: unknown, what: string, fail: ValidationFailure) => void;
-/**
- * A `z.number()`. Zod 4 rejects `NaN` AND `±Infinity` for it, and `1e999` parses
- * out of JSON as `Infinity`, so finiteness is a reachable check.
- */
-export declare const requireNumber: (value: unknown, what: string, fail: ValidationFailure) => number;
-/** A `z.enum([…])` — CLOSED, exactly like the canonical member list. */
-export declare const requireEnum: (value: unknown, allowed: readonly string[], what: string, fail: ValidationFailure) => string;
-/** A `z.array(…)`. */
-export declare const requireArray: (value: unknown, what: string, fail: ValidationFailure) => unknown[];

package/validation.js

@@ -1,117 +0,0 @@
-const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** A `z.object({…})`. */
-export const requireRecord = (value, what, fail) => {
-    if (!isRecord(value)) {
-        throw fail(`${what} is not a JSON object`);
-    }
-    return value;
-};
-/** A `z.string()`. */
-export const requireString = (value, what, fail) => {
-    if (typeof value !== "string") {
-        throw fail(`${what} is not a string`);
-    }
-    return value;
-};
-/** A `z.string().optional()`: absent is fine, present-but-wrong is not. */
-export const requireOptionalString = (value, what, fail) => {
-    if (value === undefined) {
-        return;
-    }
-    requireString(value, what, fail);
-};
-/** A `z.string().nullable()`. */
-export const requireNullableString = (value, what, fail) => {
-    if (value === null) {
-        return null;
-    }
-    return requireString(value, what, fail);
-};
-/** A `z.boolean()`. */
-export const requireBoolean = (value, what, fail) => {
-    if (typeof value !== "boolean") {
-        throw fail(`${what} is not a boolean`);
-    }
-    return value;
-};
-/** A `z.boolean().optional()`. */
-export const requireOptionalBoolean = (value, what, fail) => {
-    if (value === undefined) {
-        return;
-    }
-    requireBoolean(value, what, fail);
-};
-/**
- * A `z.number()`. Zod 4 rejects `NaN` AND `±Infinity` for it, and `1e999` parses
- * out of JSON as `Infinity`, so finiteness is a reachable check.
- */
-export const requireNumber = (value, what, fail) => {
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-        throw fail(`${what} is not a finite number`);
-    }
-    return value;
-};
-/** A `z.enum([…])` — CLOSED, exactly like the canonical member list. */
-export const requireEnum = (value, allowed, what, fail) => {
-    const text = requireString(value, what, fail);
-    if (!allowed.includes(text)) {
-        throw fail(`${what} is not one of ${allowed.join(" | ")} (${text})`);
-    }
-    return text;
-};
-/** A `z.array(…)`. */
-export const requireArray = (value, what, fail) => {
-    if (!Array.isArray(value)) {
-        throw fail(`${what} is not an array`);
-    }
-    return value;
-};
-/**
- * A `z.json()` — a JSON value, recursively: `string | number | boolean | null`,
- * an array of them, or an object of them, at ANY depth.
- *
- * WHY THIS EXISTS, given it can never fire over the wire. Every SDK response
- * has already been through `JSON.parse`, so a `Date`, `bigint`, `undefined`, or
- * function CANNOT be present by construction — this check is unreachable in
- * practice. It is here for PARITY: the canonical `sourceImageAnalysisResultSchema`
- * uses `z.json()` precisely because those four break differently on the way to
- * `jsonb` (a `bigint` throws in `JSON.stringify`, an `undefined` is silently
- * dropped, and a `Date` round-trips as an ISO *string* — a different type read
- * back than written). The mirror has to reject what the schema rejects or the
- * parity test is lying. Do not delete this as dead code.
- */
-const requireJsonValue = (value, what, fail) => {
-    if (value === null) {
-        return null;
-    }
-    if (typeof value === "string" || typeof value === "boolean") {
-        return value;
-    }
-    if (typeof value === "number") {
-        // `z.json()`'s number leaf rejects NaN and ±Infinity, and `1e999` parses out
-        // of JSON as `Infinity` — so finiteness IS reachable, unlike the rest.
-        if (!Number.isFinite(value)) {
-            throw fail(`${what} is not a finite number`);
-        }
-        return value;
-    }
-    if (Array.isArray(value)) {
-        return value.map((item, index) => requireJsonValue(item, `${what}[${index}]`, fail));
-    }
-    if (isRecord(value)) {
-        // A PLAIN object only. `isRecord` alone is not enough: it answers true for a
-        // `Date`, a `Map`, and any class instance, none of which have own enumerable
-        // entries — so recursing over them would silently accept them as `{}` while
-        // `z.json()` rejects them outright. A `Date` reaching `jsonb` is exactly the
-        // failure this check exists to stop.
-        const prototype = Object.getPrototypeOf(value);
-        if (prototype !== Object.prototype && prototype !== null) {
-            throw fail(`${what} is not a JSON value`);
-        }
-        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
-            key,
-            requireJsonValue(item, `${what}.${key}`, fail),
-        ]));
-    }
-    throw fail(`${what} is not a JSON value`);
-};