@instruments/materialgraph 0.33.0 → 0.36.0

package/search-request-types.d.ts

@@ -1,170 +0,0 @@
-/**
- * @module search-request-types
- * The two request shapes for the `/search` surface: the POST JSON body and the
- * GET query-string form. Split out of `types.ts` so neither file outgrows the
- * repo's source-size gate; every name here is re-exported from `types.ts`, so
- * no import path changes.
- */
-import type { ColourRegionRange } from "./colour-region-types.js";
-import type { CorpusScope } from "./corpus-scope-types.js";
-import type { Cursor, VariantId } from "./identifiers.js";
-import type { OpenEnum, SearchImageInput } from "./types.js";
-/**
- * One attribute filter the one search runs as a hard token set on its index
- * (ADR 0031, MG-2158). Entries on one attribute are OR'd; entries on different
- * attributes AND together.
- *
- * - `term`: the value must carry this canonical term.
- * - `terms`: any one of these terms satisfies it.
- * - `excludesTerm`: the value must not carry this term. A material that states
- *   nothing for the attribute passes.
- * - `hasValue: true`: any stated value.
- * - `min` and/or `max`: an inclusive numeric range, on a numeric attribute
- *   (`"nrc_rating"`), a dimensions lens in millimetres
- *   (`"dimensions.thickness_mm"`, `"dimensions.short_side_mm"`) or a
- *   composition share on 0 to 1 (`"composition_weighted.wool"`). It is read as
- *   the number bands wholly inside it, so a bound between two band edges is
- *   read inward; a range no band fits inside is a 400.
- *
- * `attributeId` is an attribute the index carries tokens for, or
- * `"certification_programme"` for any certification programme. Terms are
- * canonical dictionary terms, not display names. Numeric attributes take
- * `hasValue` or a range. An attribute or term the index does not carry is a
- * 400 naming it.
- */
-export type SearchIndexFilter = {
-    attributeId: string;
-    term: string;
-} | {
-    attributeId: string;
-    terms: string[];
-} | {
-    attributeId: string;
-    excludesTerm: string;
-} | {
-    attributeId: string;
-    hasValue: true;
-} | {
-    attributeId: string;
-    min?: number;
-    max?: number;
-};
-/**
- * The POST `/search` JSON body (ADR 0031): the words, or a look-alike seed, and
- * the page wanted. `category`, `filters`, `corpusScope`, `colour` and `brands`
- * become fields of the query's plan and run in the same index query. The order
- * is the index's own, so nothing here sets weights, a blend or a sort. Send
- * `text`, `similarTo`, `image`, `colour`, `category`, `filters` or `brands`; a
- * corpus scope alone does not say what to find. Any other field is a 400
- * naming it.
- */
-export type SearchInput = {
-    /**
-     * Free text ("oak flooring", "sage green velvet", "Kvadrat wool"). Brands,
-     * categories, colours and attributes are read from the words unless
-     * `brands`, `category` or `colour` says so instead; a corrected word is
-     * reported under `correctedQuery`.
-     */
-    text?: string;
-    /** A query image (URL or base64); `text`, when also given, narrows it. */
-    image?: SearchImageInput;
-    /**
-     * Materials that LOOK like a seed: an existing variant, a Material Bank SKU
-     * (an unknown SKU is a 400 naming it), or a pre-computed image vector.
-     */
-    similarTo?: {
-        variantId: VariantId;
-    } | {
-        materialBankId: string;
-    } | {
-        vector: string;
-    };
-    /**
-     * A hard category gate: public category-group or product-type names, or
-     * taxonomy keys. It replaces the category the words were read as. An
-     * unknown value is a 400 listing every valid name.
-     */
-    category?: {
-        filter: string[];
-    };
-    /** Hard attribute filters, 1 to 24. See {@link SearchIndexFilter}. */
-    filters?: SearchIndexFilter[];
-    /**
-     * Order the page by a colour: a `hex`, or `variantId` for the colour of an
-     * existing Variant. The page is the colour's family, nearest first by OKLab
-     * distance; it replaces any colour read from `text`. A Variant with no colour
-     * on the index is a 400.
-     *
-     * `oklab` and `range` are additive: send them when you already resolved the
-     * exact OKLab point or the named colour's region (see `resolveColour()`), and
-     * the plan carries that colour without re-deriving it from `hex`. `hex` stays
-     * required.
-     */
-    colour?: {
-        hex: string;
-        oklab?: [number, number, number];
-        range?: ColourRegionRange;
-    } | {
-        variantId: VariantId;
-    };
-    /**
-     * Brands the page must come from: canonical brand ids, exact slugs
-     * ("sherwin-williams") or exact display names ("Sherwin-Williams"), up to
-     * 50. They replace the brands `text` was read as. An empty list is the
-     * same request as omitting it — every brand. An unrecognised value is a
-     * 400 naming it; a display name shared by more than one brand is a 400
-     * naming the exact slugs to choose between; a brand MaterialGraph holds no
-     * materials under is a 400 naming a populated sibling when one exists.
-     */
-    brands?: string[];
-    /**
-     * Attribute ids (at most 8) whose resolved value should ride each result
-     * under `attributes`, keyed by attribute id. Not a plan field: it changes
-     * no ordering and plays no part in the cursor. An attribute you did not
-     * ask for is not a key on `attributes` at all; one you asked for that a
-     * result carries no accepted value for is `null`; anything else is the
-     * value. An unknown attribute id is a 400 naming it.
-     */
-    returnAttributes?: string[];
-    /**
-     * Which corpus to answer from, applied inside the index query. ABSENT (or
-     * `"all"`) means the whole graph. `"materialBankOrderable"` is a provenance
-     * signal (a Material Bank identity), not a storefront; the channel-backed
-     * scopes (`"materialBankNaOrderable"`, `"materialBankEuOrderable"`,
-     * `"designShopOrderable"`) answer where a material can be ordered,
-     * `"materialBankNaAndCatalogue"` is a governed discovery corpus (the union
-     * of Material Bank North America and Catalogue editorial membership, not a
-     * buyability claim), and `"samplizeCatalogue"` admits published US Samplize
-     * paint colours, regardless of stock.
-     */
-    corpusScope?: CorpusScope;
-    /** Products per page (max 60). Absent, the search's own page size. */
-    limit?: number;
-    /**
-     * The previous response's `cursor`, passed back verbatim. A cursor from
-     * another query (other words, filters or scope) is a 409.
-     */
-    cursor?: Cursor;
-    /** Add `timings` and `explain.plan`, the plan the search ran on. */
-    explain?: boolean;
-    /** Result projection: `"full"` (default) or the lean `"card"` grid form. */
-    view?: OpenEnum<"full" | "card">;
-};
-/**
- * Query-string params for the GET `/search` form. `category` and `filters`
- * have no query-string form; send them through `search()`.
- */
-export type SearchGetParams = {
-    q?: string;
-    /** Seed the search from this variant's image. Opaque; pass it through verbatim. */
-    variantId?: VariantId;
-    /** Corpus applied inside the index query; absent means the whole graph. */
-    corpusScope?: CorpusScope;
-    limit?: number;
-    /** The previous response's `cursor`, passed back verbatim. */
-    cursor?: Cursor;
-    /** Result projection: `"full"` (default) or the lean `"card"` grid form. */
-    view?: OpenEnum<"full" | "card">;
-    /** `"1"` adds `timings` and `explain.plan`. */
-    explain?: OpenEnum<"0" | "1">;
-};

package/search-request-types.js

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

package/search-response-receipt-types.d.ts

@@ -1,24 +0,0 @@
-/**
- * @module sdk/search-response-receipt-types
- * @description The ranking source and the explain-only plan receipt a Search
- * response carries.
- */
-import type { SearchPlanReceipt } from "./search-index-plan-types.js";
-import type { OpenEnum } from "./types.js";
-/**
- * What ordered the page: `image` (a look-alike), `colour` (colour distance
- * inside the named colour's family), `lexical` (the query's words, by text
- * rank on the index), `attribute` (the category and filters alone define the
- * page) or `agent` (the search agent chose the variants and their order).
- */
-export type SearchMode = OpenEnum<"image" | "colour" | "lexical" | "agent" | "attribute">;
-/** The explain-only receipt shared by full and card search responses. */
-export type SearchResponseExplainReceipts = {
-    /**
-     * Present under `explain` only: the receipt of the plan the one search ran
-     * on, with the plan itself (ADR 0031). Diagnostic, like `timings`.
-     */
-    explain?: {
-        plan: SearchPlanReceipt;
-    };
-};

package/search-response-receipt-types.js

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

package/search-response-types.d.ts

@@ -1,11 +0,0 @@
-import type { SearchData } from "./types.js";
-/** Canonical Search wire response. Raw SDK methods preserve this envelope. */
-export type SearchResponse = {
-    data: SearchData;
-    meta: {
-        operationId: "search_materials_post" | "search_materials_get";
-        requestId: string;
-    };
-    links: Record<string, never>;
-    warnings: never[];
-};

package/search-response-types.js

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

package/search-result-validation.d.ts

@@ -1,9 +0,0 @@
-import type { ValidationFailure } from "./validation.js";
-/**
- * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
- * the first field that does not match `searchResultItemSchema`. Checks the shape
- * only — unknown keys ride through untouched, per the SDK's pass-through
- * contract (nothing on the emit path parses, so stripping would invent a
- * normalisation the wire never had).
- */
-export declare const checkSearchResultItem: (value: unknown, what: string, fail: ValidationFailure) => void;

package/search-result-validation.js

@@ -1,83 +0,0 @@
-/**
- * The one runtime validator for a {@link SearchResultItem} on the wire — the
- * hand-rolled, zero-runtime-dependency mirror of `searchResultItemSchema`
- * (`packages/products/src/search/search-result-schema.ts`) and its full
- * transitive closure, including `searchResultSignalsSchema`.
- *
- * WHY THIS EXISTS SEPARATELY FROM THE TYPE MIRROR. `contract-parity.test.ts`
- * proves the SDK's STATIC types match the canonical schemas. That is a
- * compile-time proof about shapes; it validates nothing at run time. A malformed
- * result item arriving over a stream was caught by neither, so the Match reader
- * now checks every item through here.
- *
- * ONE HOME. This module is the single implementation — no copy lives inside
- * `match-stream.ts`. It is package-internal (not re-exported from `index.ts`)
- * because a published symbol is a permanent contract, and nothing outside the
- * SDK needs to call it yet; promoting it later is additive.
- *
- * ENUMS ARE CLOSED, matching the canonical `z.enum(…)` members.
- */
-import { requireArray, requireBoolean, requireEnum, requireNullableString, requireNumber, requireOptionalBoolean, requireOptionalString, requireRecord, requireString, } from "./validation.js";
-// ── Leaf checks ──────────────────────────────────────────────────────────────
-/** `palette[]` — `{ hex, proportion, name: string.nullable().optional() }`. */
-const checkPaletteSwatch = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    requireString(record.hex, `${what}.hex`, fail);
-    requireNumber(record.proportion, `${what}.proportion`, fail);
-    // `.nullable().optional()` — absent OR null OR a string.
-    if (record.name !== undefined) {
-        requireNullableString(record.name, `${what}.name`, fail);
-    }
-};
-/** `colourMeta` — three independently optional strings. */
-const checkColourMeta = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    requireOptionalString(record.mood, `${what}.mood`, fail);
-    requireOptionalString(record.dominantFamily, `${what}.dominantFamily`, fail);
-    requireOptionalString(record.dominantHex, `${what}.dominantHex`, fail);
-};
-// ── The item ─────────────────────────────────────────────────────────────────
-/**
- * Prove one wire value is a {@link SearchResultItem}, raising through `fail` at
- * the first field that does not match `searchResultItemSchema`. Checks the shape
- * only — unknown keys ride through untouched, per the SDK's pass-through
- * contract (nothing on the emit path parses, so stripping would invent a
- * normalisation the wire never had).
- */
-export const checkSearchResultItem = (value, what, fail) => {
-    const record = requireRecord(value, what, fail);
-    requireString(record.variantId, `${what}.variantId`, fail);
-    requireString(record.brand, `${what}.brand`, fail);
-    requireString(record.product, `${what}.product`, fail);
-    requireNullableString(record.brandSlug, `${what}.brandSlug`, fail);
-    requireNullableString(record.productId, `${what}.productId`, fail);
-    // `z.string().optional()` — absent, or a string. NOT nullable: the emit path
-    // omits the key rather than sending null when no MB identity is known.
-    requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
-    requireOptionalString(record.manufacturerCode, `${what}.manufacturerCode`, fail);
-    if (record.projectSaveCapability !== undefined) {
-        requireEnum(record.projectSaveCapability, ["allowed"], `${what}.projectSaveCapability`, fail);
-    }
-    if (record.sourceStatus !== undefined) {
-        requireEnum(record.sourceStatus, ["provisional"], `${what}.sourceStatus`, fail);
-    }
-    // Same shape as `materialBankId`: absent, or a string. The emit path omits
-    // the key when no primary product type is on record rather than sending null,
-    // so "we don't know what this is" and "this is a null kind of thing" cannot
-    // be confused.
-    requireOptionalString(record.productType, `${what}.productType`, fail);
-    requireNullableString(record.color, `${what}.color`, fail);
-    requireNullableString(record.variantName, `${what}.variantName`, fail);
-    requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);
-    requireBoolean(record.hasImage, `${what}.hasImage`, fail);
-    requireNumber(record.score, `${what}.score`, fail);
-    const palette = requireArray(record.palette, `${what}.palette`, fail);
-    palette.forEach((swatch, index) => {
-        checkPaletteSwatch(swatch, `${what}.palette[${index}]`, fail);
-    });
-    if (record.colourMeta !== undefined) {
-        checkColourMeta(record.colourMeta, `${what}.colourMeta`, fail);
-    }
-    requireOptionalBoolean(record.retired, `${what}.retired`, fail);
-    requireOptionalBoolean(record.sampleable, `${what}.sampleable`, fail);
-};

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[];