@instruments/materialgraph 0.25.0 → 0.27.0

package/material-composition-types.d.ts

@@ -0,0 +1,403 @@
+/**
+ * Hand-mirrored wire types for MATERIAL composition — what a product is made
+ * of (`GET /api/v1/materials/{variantId}/composition`, operation
+ * `get_material_composition`, and `GET /api/v1/composition/report`, operation
+ * `get_composition_report`; MG-1969).
+ *
+ * Composition means only this. It is unrelated to `./slot-pool-types.ts`,
+ * the candidate pools a scheme composer outside MaterialGraph reads.
+ *
+ * Like the rest of the SDK these interfaces carry NO runtime dependency on any
+ * `@materialgraph/*` package; they mirror the `VariantComposition` and
+ * `CompositionCorpusSummary` shapes in `apps/web/public/openapi.yaml`.
+ *
+ * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
+ * so a new server value still type-checks; objects are read structurally. The
+ * one exception is {@link VariantCompositionAbsence}, which is closed —
+ * see below.
+ */
+import type { VariantId } from "./identifiers.js";
+import type { OpenEnum } from "./types.js";
+/**
+ * Why no parse stands behind a material. CLOSED on purpose: a consumer must
+ * branch on every arm, and widening it would let a new reason fall through a
+ * branch that reads "one of these two, so it must be the other".
+ *
+ * - `no_material_bank_sku` — the variant was never a Material Bank SKU, so
+ *   there is no catalogue row anyone could have parsed.
+ * - `not_linked` — it has a SKU and the corpus has not reached it. A statement
+ *   about MaterialGraph's coverage, never about the material.
+ *
+ * Neither is the same as a present parse whose `status` is `empty`: that is the
+ * catalogue row saying it declared nothing, which is knowledge.
+ */
+export type VariantCompositionAbsence = "no_material_bank_sku" | "not_linked";
+/** `failed_closed` means the parser refused rather than guessed. */
+export type CompositionParseStatus = OpenEnum<"parsed" | "empty" | "failed_closed">;
+/** One document or catalogue column the record's facts are taken from. */
+export type CompositionSource = {
+    id: string;
+    kind: OpenEnum<"epd" | "hpd" | "technical_document" | "manufacturer" | "reseller" | "test_report" | "catalogue_field" | "inference" | "other">;
+    /** A URL, a document name, or the catalogue column name. */
+    locator: string;
+    retrievedAt?: string;
+    /** The source's wording, verbatim. Never corrected or completed. */
+    statement?: string;
+    title?: string;
+};
+/**
+ * A percentage as the source gives it, or one of the four ways a source can
+ * name a node and still withhold the number. `undisclosed` holds its place in
+ * the sum; `alternate` sits outside it.
+ */
+export type CompositionAmount = {
+    kind: "exact";
+    value: number;
+} | {
+    kind: "range";
+    max: number;
+    min: number;
+} | {
+    kind: "bound";
+    operator: OpenEnum<"at_most" | "at_least" | "less_than" | "greater_than">;
+    value: number;
+} | {
+    kind: "unknown";
+} | {
+    kind: "undisclosed";
+    reason: OpenEnum<"trade_secret" | "not_provided">;
+} | {
+    kind: "conditionally_present";
+    max: number;
+} | {
+    kind: "band";
+    band: string;
+    version: string;
+    vocabulary: string;
+} | {
+    kind: "alternate";
+} | {
+    kind: string;
+};
+/** How much of its parent, or of the whole product, a node is. */
+export type CompositionShare = {
+    amount: CompositionAmount;
+    /** What the percentage measures, only as the source says it. Never converted. */
+    basis: OpenEnum<"mass" | "volume" | "fibre_mass" | "area" | "count" | "thickness" | "unspecified">;
+    of: OpenEnum<"parent" | "product">;
+    source: string;
+};
+/** An absolute figure the source states, in its own unit. Never in the sum. */
+export type CompositionQuantity = {
+    amount: {
+        kind: "exact";
+        value: number;
+    } | {
+        kind: "range";
+        max: number;
+        min: number;
+    } | {
+        kind: "bound";
+        operator: OpenEnum<"at_most" | "at_least" | "less_than" | "greater_than">;
+        value: number;
+    } | {
+        kind: string;
+    };
+    /** The figure and unit as the source writes them. */
+    raw: string;
+    unit: OpenEnum<"mm" | "in" | "mil" | "gauge" | "oz_yd2" | "g_m2" | "kg" | "kg_m3" | "pcf" | "dtex" | "denier" | "ply">;
+};
+/**
+ * Which substance a component is. `resolution` is the field to read before
+ * trusting `term`: `identified` is the only arm carrying a dictionary id that
+ * means what the source said.
+ */
+export type CompositionTermRef = {
+    /** The source's own words, verbatim. */
+    raw: string;
+    resolution: OpenEnum<"identified" | "proprietary" | "withheld" | "unresolved">;
+    source?: string;
+    term?: string;
+};
+/** Dictionary ids qualifying a term without changing it. */
+export type CompositionModifiers = {
+    brand?: string;
+    cut?: string;
+    grade?: string;
+    origin?: string;
+    process?: string[];
+    provenance?: string;
+    treatment?: string[];
+};
+/** A statement about a node that is not a share. Claims never enter the sum. */
+export type CompositionClaim = {
+    amount?: CompositionAmount;
+    kind: OpenEnum<"free_of" | "contains" | "recyclable" | "renewable" | "bio_based" | "biodegradable" | "compostable" | "certified" | "other">;
+    /** The claim's wording, verbatim. */
+    raw: string;
+    source: string;
+    term?: string;
+};
+/** The level above which the source says every substance is listed. */
+export type CompositionThreshold = {
+    raw: string;
+    regime: OpenEnum<"100_ppm" | "1000_ppm" | "ghs_sds" | "other">;
+    scope: OpenEnum<"product" | "material">;
+    source: string;
+};
+/**
+ * Whether the source presents a node's children as exhaustive. `partial` and
+ * `unspecified` are both statements about the SOURCE; neither licenses adding
+ * a child to make a list add up.
+ */
+export type CompositionCoverage = {
+    claim: OpenEnum<"complete" | "partial" | "unspecified">;
+    source?: string;
+    threshold?: CompositionThreshold;
+};
+/** Why the unstated part of a composition is unstated. */
+export type CompositionRemainder = {
+    kind: "legally_omitted";
+    regime: OpenEnum<"eu_1007_2011" | "us_16_cfr_303">;
+    rule: string;
+    source: string;
+} | {
+    kind: "undisclosed";
+    reason: OpenEnum<"trade_secret" | "not_provided">;
+    source: string;
+} | {
+    kind: string;
+};
+/** One named substance with its share. Never an unstated remainder. */
+export type CompositionComponent = {
+    claims: CompositionClaim[];
+    /** "Of which" subsets of this component; their shares are of it. */
+    components?: CompositionComponent[];
+    id: string;
+    identity: CompositionTermRef;
+    modifiers: CompositionModifiers;
+    quantity?: CompositionQuantity;
+    /** What the substance does inside its part, only where the source says. */
+    role?: string;
+    share: CompositionShare;
+    source: string;
+};
+/** A layer or piece of the product. Sibling parts are co-present and sum. */
+export type CompositionPart = {
+    claims: CompositionClaim[];
+    components: CompositionComponent[];
+    construction: string[];
+    coverage: CompositionCoverage;
+    id: string;
+    /** The part's name as the source writes it. */
+    label?: string;
+    /** Alternatives the buyer chooses between; options never sum with siblings. */
+    options?: CompositionPart[];
+    parts?: CompositionPart[];
+    /** Stacking order among siblings: 0 is the top or outer face. */
+    position: number;
+    quantity?: CompositionQuantity;
+    remainder?: CompositionRemainder;
+    role?: string;
+    share: CompositionShare;
+    source: string;
+};
+/** The composition of one product, as the cited sources state it. */
+export type CompositionRecord = {
+    claims: CompositionClaim[];
+    /** The whole product's own inventory; never summed with `parts`. */
+    components: CompositionComponent[];
+    construction: string[];
+    coverage: CompositionCoverage;
+    id: string;
+    name: string;
+    /** Alternatives the buyer chooses between, each a full record. */
+    options?: CompositionRecord[];
+    parts: CompositionPart[];
+    primarySource?: string;
+    remainder?: CompositionRemainder;
+    sources: CompositionSource[];
+};
+/**
+ * The record flattened to the `composition_weighted` attribute value.
+ *
+ * `basis: "tokens_only"` says the PROPORTIONS are unknown, never that the
+ * components are, and every entry then carries a component with no `fraction`.
+ * An absent `fraction` is an unknown share; `0` is a declared none.
+ */
+export type CompositionWeightedValue = {
+    basis: OpenEnum<"declared_percent" | "single_material" | "tokens_only">;
+    components: {
+        /** A `composition_component` dictionary term id. */
+        component: string;
+        /** 0 to 1, never a percentage. */
+        fraction?: number;
+        tolerance?: number;
+    }[];
+    [key: string]: unknown;
+};
+/** What meeting a need lets a reader do with the record. */
+export type CompositionUnlock = OpenEnum<"specify" | "substitute" | "compare">;
+/**
+ * Why a record was not measured against a bar. Null exactly when
+ * `completeness` is present. CLOSED, like {@link VariantCompositionAbsence}:
+ * a consumer must branch on every arm.
+ *
+ * - `no_record` — nothing was parsed, so there is nothing to measure.
+ * - `no_product_type` — a record exists, but the tuple resolved to no product
+ *   type, so there is no bar to pick.
+ * - `no_bar_set` — both exist and MaterialGraph has authored no requirement
+ *   for that product type. A gap in OUR registry. Rendering it as an unscored
+ *   record reads as a fault in the maker's data.
+ */
+export type CompositionCompletenessAbsence = "no_record" | "no_product_type" | "no_bar_set";
+/**
+ * A record measured against its product type's authored bar, AT READ TIME.
+ * Absent (rather than zeroed) when it could not be measured; read
+ * `completenessAbsent` for which of the three reasons applies.
+ */
+export type CompositionCompleteness = {
+    met: number;
+    needs: {
+        id: string;
+        label: string;
+        met: boolean;
+        unlocks: CompositionUnlock[];
+    }[];
+    productTypeId: string;
+    /** met / total, 0 to 1, to three decimal places. */
+    share: number;
+    total: number;
+    /** Open when every need tagged with it is met. */
+    unlocks: {
+        compare: boolean;
+        specify: boolean;
+        substitute: boolean;
+    };
+};
+/** The stored parse, with the contract it was written under. */
+export type VariantCompositionParse = {
+    parseKey: string;
+    status: CompositionParseStatus;
+    /** Null when the parse stored none; `empty` and `failed_closed` always do. */
+    record: CompositionRecord | null;
+    projection: CompositionWeightedValue | null;
+    /** Unresolved wording, or the error text when the parse failed closed. */
+    unresolved: {
+        raw: string;
+        source: string;
+    }[];
+    modelId: string;
+    schemaVersion: string;
+    dictionaryVersion: string;
+    parsedAt: string;
+};
+/**
+ * What a material is made of, traced to the catalogue columns it came from.
+ *
+ * READ `absent` FIRST. When it is set there is no parse, and its value says
+ * why. When it is null there is a parse, and `parse.status` may still be
+ * `empty` — the catalogue row was read and declared nothing.
+ *
+ * `productType` is inferred for the TUPLE, which many products share, so it is
+ * never a statement about this variant's own category.
+ */
+export type VariantComposition = {
+    variantId: VariantId;
+    materialBankSku: string | null;
+    /** The verbatim catalogue cells, keyed by column name. */
+    catalogue: {
+        tuple: Record<string, string>;
+    } | null;
+    parse: VariantCompositionParse | null;
+    productType: {
+        id: string;
+        share: number | null;
+    } | null;
+    completeness: CompositionCompleteness | null;
+    /** Null exactly when `completeness` is present. */
+    completenessAbsent: CompositionCompletenessAbsence | null;
+    absent: VariantCompositionAbsence | null;
+};
+/** A count in both currencies. The Live SKU figure is the answer. */
+export type CompositionCorpusWeight = {
+    tuples: number;
+    liveSkus: number;
+};
+export type CompositionCorpusShare = CompositionCorpusWeight & {
+    liveSkuShare: number | null;
+    tupleShare: number | null;
+};
+export type CompositionCorpusNeedCoverage = {
+    id: string;
+    label: string;
+    unlocks: CompositionUnlock[];
+    /** Share of the type's measured Live SKUs whose record meets this need. */
+    liveSkuShare: number | null;
+    tupleShare: number | null;
+};
+export type CompositionCorpusTypeCoverage = {
+    productTypeId: string;
+    measured: CompositionCorpusWeight;
+    failedClosed: CompositionCorpusWeight;
+    empty: CompositionCorpusWeight;
+    needs: CompositionCorpusNeedCoverage[];
+    /**
+     * Share of the type's measured rows meeting EVERY need — the whole bar.
+     * Not the same as an unlock being open, which only requires the needs
+     * tagged with that unlock. Draw a completeness bar from this.
+     */
+    complete: {
+        liveSkuShare: number | null;
+        tupleShare: number | null;
+    };
+    unlocks: {
+        compare: number | null;
+        specify: number | null;
+        substitute: number | null;
+    };
+    /** The need the most Live SKUs are missing, or null when every need is met. */
+    mostMissedNeed: {
+        id: string;
+        label: string;
+        liveSkus: number;
+    } | null;
+};
+/**
+ * How far the material composition corpus has got.
+ *
+ * `authoringQueue` lists product types SKUs were assigned to but no
+ * requirement has been written for. They have NO BAR SET, which is why they
+ * are listed apart rather than scored zero.
+ */
+export type CompositionCorpusSummary = {
+    completeness: {
+        authoringQueue: (CompositionCorpusWeight & {
+            productTypeId: string;
+        })[];
+        byProductType: CompositionCorpusTypeCoverage[];
+        unknownProductType: CompositionCorpusWeight;
+    };
+    coverage: {
+        failedClosed: CompositionCorpusWeight;
+        /** Tuples with no text to parse at all; not a parser failure. */
+        noValue: CompositionCorpusWeight;
+        resolvable: CompositionCorpusShare;
+        validity: CompositionCorpusShare;
+        withValue: CompositionCorpusWeight;
+    };
+    dictionaryVersion: string;
+    /** The corpus's own list-price spend, never a per-request figure. */
+    tokens: {
+        costUsd: {
+            input: number;
+            output: number;
+            total: number;
+        };
+        inputTokens: number;
+        outputTokens: number;
+    };
+    parses: number;
+    linkedSkus: number;
+    generatedAt: string;
+};

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

@@ -1,154 +1,70 @@
 /** Hand-mirrored wire types for `POST /api/v1/search/plan`. */
-import type { QuerySense } from "./query-understanding-types.js";
-import type { ResolvedMeaning } from "./resolve-types.js";
-import type { SearchInput } from "./search-request-types.js";
 import type { OpenEnum } from "./types.js";
-export type MaterialQueryVocabularyKind = OpenEnum<"attribute" | "dictionary_term" | "inline_enum" | "product_type" | "product_type_group">;
-export interface MaterialQuerySpan {
-    start: number;
-    end: number;
-    text: string;
-}
-export interface MaterialQueryOwner {
-    attributeId: string;
-    attributeName: string;
-}
-export interface MaterialQueryLifecycle {
-    status: string;
-    introducedIn?: string;
-    deprecatedIn?: string;
-    supersededBy?: string;
-}
-export type MaterialQueryOntologyContext = {
-    description: string;
-    valueKind: string;
-    valueDictionaryId?: string;
-} | {
-    dictionaryId: string;
-    dictionaryName: string;
-    owningAttributes: Array<{
-        id: string;
-        name: string;
-    }>;
-    lifecycle: MaterialQueryLifecycle;
-} | {
+/** One wanted value: hard filters the page, soft only orders it. */
+export type MaterialQueryWant = {
     attributeId: string;
-    attributeName: string;
-} | {
-    description: string;
-    lifecycle: MaterialQueryLifecycle;
-    parentProductTypeGroupId?: string;
-} | {
-    description: string;
+    terms: string[];
+    phrase: string;
+    strength: OpenEnum<"hard" | "soft">;
+    fill: number;
 };
-export interface MaterialQueryApplicability {
-    status: OpenEnum<"all" | "some" | "none" | "unknown">;
-    categoryId?: string;
-    productTypeIds: string[];
-    applicableProductTypeIds: string[];
-}
-export interface MaterialQueryCoverage {
-    variants: number;
-    basis: OpenEnum<"facet_index">;
-    scope: OpenEnum<"corpus">;
-}
-export interface MaterialQueryReachability {
-    status: OpenEnum<"positive" | "zero" | "unknown">;
-    categoryId: string;
-    basis: OpenEnum<"bounded_probe" | "unmeasured">;
-}
-export interface MaterialQueryCandidate {
-    kind: MaterialQueryVocabularyKind;
-    subjectType: MaterialQueryVocabularyKind;
-    subjectId: string;
-    label: string;
-    context: MaterialQueryOntologyContext;
-    score: number;
-    tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
-    evidence: {
-        source: OpenEnum<"registry" | "query_domain_embedding">;
-        span: MaterialQuerySpan;
-    };
-    outcome: OpenEnum<"recognized" | "suggested" | "executable" | "ambiguous" | "refused">;
-    owners: MaterialQueryOwner[];
-    selectedOwner?: MaterialQueryOwner;
-    applicability?: MaterialQueryApplicability;
-    coverage?: MaterialQueryCoverage;
-    reachability?: MaterialQueryReachability;
-    reason?: string;
-}
-export interface MaterialQueryCriterion {
-    source: {
-        subjectType: MaterialQueryVocabularyKind;
-        subjectId: string;
-        span: MaterialQuerySpan;
-    };
-    attribute: {
-        id: string;
-        name: string;
-    };
-    ownerAlternatives: MaterialQueryOwner[];
-    operator: OpenEnum<"term" | "presence" | "numeric_range">;
-    term?: string;
-    min?: number;
-    max?: number;
-    coverage: MaterialQueryCoverage;
-    applicability: MaterialQueryApplicability;
-    reachability?: MaterialQueryReachability;
-}
-export type MaterialQueryStandardMeaning = ResolvedMeaning | QuerySense;
-export type MaterialQueryAmbiguityAlternative = (MaterialQueryOwner & {
-    kind: OpenEnum<"owner">;
-}) | {
-    kind: OpenEnum<"subject">;
-    subjectType: MaterialQueryVocabularyKind;
-    subjectId: string;
-    label: string;
-} | {
-    kind: OpenEnum<"standard_meaning">;
-    meaning: MaterialQueryStandardMeaning;
+export type MaterialQueryExclusion = {
+    attributeId: string;
+    term: string;
+    phrase: string;
 };
-export interface MaterialQueryPlan {
-    version: OpenEnum<"1">;
-    verdict: OpenEnum<"executable" | "partial" | "refused">;
-    rawQuery: string;
-    normalisedQuery: string;
-    registry: {
-        corpusSize: number;
-        contentHash: string;
-    };
-    candidates: MaterialQueryCandidate[];
+/** The dictionary reading of one query, as the index search runs it. */
+export type MaterialQueryReading = {
+    normalised: string;
     category: {
-        key: string;
-        name: string;
-        level: OpenEnum<"group" | "type">;
-        parentKey: string | null;
-        source: {
-            subjectType: MaterialQueryVocabularyKind;
-            subjectId: string;
-            span: MaterialQuerySpan;
-        };
+        productTypeIds: string[];
+        label: string;
+        phrase: string;
+    } | null;
+    brands: {
+        ids: string[];
+        names: string[];
+        phrase: string;
     } | null;
-    criteria: MaterialQueryCriterion[];
+    wants: MaterialQueryWant[];
+    excludes: MaterialQueryExclusion[];
+    excludeBrands: string[];
     colour: {
-        family?: string;
-        undertone?: string;
+        phrase: string;
+        familyId: string;
+        hex: string;
+        oklab: [number, number, number];
+        family12: string[];
     } | null;
-    residualText: string;
-    unspentSpans: Array<MaterialQuerySpan & {
-        reason: OpenEnum<"residual" | "ambiguous" | "refused">;
-    }>;
-    ambiguities: Array<{
-        subjectType: MaterialQueryVocabularyKind;
-        subjectId: string;
-        span: MaterialQuerySpan;
-        reason: string;
-        alternatives: MaterialQueryAmbiguityAlternative[];
-    }>;
-    standardMeanings: Array<{
-        span: MaterialQuerySpan;
-        meanings: MaterialQueryStandardMeaning[];
-    }>;
-    /** Complete ordinary-search requests authored by MaterialGraph. Execute verbatim. */
-    requests: SearchInput[];
-}
+    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-resources-client.d.ts

@@ -1,18 +1,20 @@
-/** Material blocks, safe assets, and technical documents over one shared transport. */
-import { HttpTransport } from "./http-transport.js";
+/** Material blocks, a variant's assets, and technical documents over one shared transport. */
+import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
-import type { MaterialAssetProjection, MaterialDocumentPage, MaterialDocumentPageOptions } from "./material-asset-types.js";
+import type { ListVariantAssetsOptions, MaterialDocumentPage, MaterialDocumentPageOptions, VariantAssetPage } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
-import type { MaterialRenderAssets } from "./render-assets-types.js";
 /** Read known and explicitly unobserved canonical material fields. */
-export declare function materialBlocks(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialBlockProjection>;
-/** Read only redistribution-safe images and downloads for a material. */
-export declare function materialAssets(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialAssetProjection>;
-/** Read the accepted render-ready appearance projection, or an explicit unavailable reason. */
-export declare function materialRenderAssets(transport: HttpTransport, variantId: VariantId, signal?: AbortSignal): Promise<MaterialRenderAssets>;
+export declare const materialBlocks: (transport: HttpTransport, variantId: VariantId, signal?: AbortSignal) => Promise<MaterialBlockProjection>;
+/**
+ * Read one bounded, filtered, cursor-paged page of a variant's images and
+ * files. `imageRoles` narrows only images and `documentTypes` narrows only
+ * documents, each implying its own kind; the server refuses either paired
+ * with other kinds, or with each other, rather than silently widening.
+ */
+export declare const listVariantAssets: (transport: HttpTransport, variantId: VariantId, options?: ListVariantAssetsOptions, signal?: AbortSignal) => Promise<VariantAssetPage>;
 /**
  * Read the owning Product's URL-deduplicated document page. Variant declarations
  * retain exact attribution; consumers inspect `appliesToRequestedVariant`
  * before presenting a sibling Variant declaration as applicable.
  */
-export declare function materialDocuments(transport: HttpTransport, variantId: VariantId, options?: MaterialDocumentPageOptions, signal?: AbortSignal): Promise<MaterialDocumentPage>;
+export declare const materialDocuments: (transport: HttpTransport, variantId: VariantId, options?: MaterialDocumentPageOptions, signal?: AbortSignal) => Promise<MaterialDocumentPage>;