@instruments/materialgraph 0.26.0 → 0.27.1

package/material-asset-types.d.ts

@@ -1,43 +1,80 @@
 /**
- * Wire types for the material ASSET projection
- * (`GET /api/v1/materials/{variantId}/assets`).
+ * Wire types for `list_variant_assets`
+ * (`GET /api/v1/variants/{variantId}/assets`, MG-2232): one bounded, filtered,
+ * cursor-paged page of a variant's images and files.
  *
- * THE LENS: "what may I show for this material?" — the redistribution-safe
- * images and downloads, not every file on record. An asset absent here is not
- * an asset that does not exist; it is one this surface does not hand out.
+ * Classification (`kind`, `imageRole`, `presentation`, `documentTypes`)
+ * mirrors the one registry `@materialgraph/schema/asset-classification`
+ * carries server-side; every field that names a registry term is an
+ * {@link OpenEnum} so a server-added term still type-checks here.
  */
 import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
-export type MaterialAssetVisualRole = OpenEnum<"grid" | "detail" | "scene" | "swatch" | "technical" | "unknown">;
 /**
- * Whether we hold the bytes.
- *  - `downloaded` — held and served by us.
- *  - `linked_not_downloaded` — the source names it; we have not fetched it. Not
- *    a broken asset.
- *  - `failed` — we tried and could not. Says nothing about the source.
- *  - `retired_placeholder` — a stand-in for a withdrawn asset.
+ * `available`: MaterialGraph serves the file at `url`. `unknown`: `url` is the
+ * maker's own link, unchecked. `unavailable`: no working copy is known and
+ * `url` is null.
  */
-export type MaterialAssetStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "failed" | "retired_placeholder">;
-export type MaterialAssetProjectionImage = {
-    key: string;
-    ordinal: number;
-    proxyPath: string;
-    visualRole: MaterialAssetVisualRole;
-    status: MaterialAssetStatus;
-    contentType: string | null;
-    fileExtension: string | null;
-    filename: string | null;
-    byteSize: number | null;
+export type VariantAssetAvailability = OpenEnum<"available" | "unknown" | "unavailable">;
+/** What an image primarily shows. */
+export type VariantImageRole = OpenEnum<"product" | "swatch" | "detail" | "scene" | "technical" | "colour_chart" | "sample_collection" | "other" | "unknown">;
+/** How an image must be framed, a different question from what it shows. */
+export type VariantImagePresentation = OpenEnum<"edge_to_edge" | "packshot" | "cutout_margin" | "montage" | "unknown">;
+/** What a document is for; a document can carry more than one purpose. */
+export type VariantDocumentType = OpenEnum<"technical_data_sheet" | "product_sheet" | "technical_bulletin" | "sustainability_report" | "specification" | "installation_guide" | "care_maintenance_guide" | "operation_manual" | "warranty" | "parts_list" | "technical_drawing" | "test_report" | "certificate" | "declaration_of_performance" | "environmental_product_declaration" | "health_product_declaration" | "ingredient_disclosure" | "safety_data_sheet" | "brochure" | "catalogue" | "colour_finish_chart" | "other" | "unknown">;
+/** Every asset kind the registry knows. */
+export type VariantAssetKind = OpenEnum<"image" | "document" | "cad" | "bim" | "model_3d" | "texture" | "archive" | "other" | "unknown">;
+/**
+ * One asset. A field is absent only where it says so: kind-scoped fields
+ * appear on their kind, and an absent value is unknown. `url` is absent when
+ * `availability` is `unavailable`; `appliesTo` appears only as `product`.
+ */
+export type VariantAssetItem = {
+    /** Only `product`: filed against the whole product. Absent: this variant's own. */
+    appliesTo?: "product";
+    assetId: string;
+    availability: VariantAssetAvailability;
+    /** Not on images; absent when unknown. */
+    byteSize?: number;
+    /** Documents only; absent when unknown. */
+    documentTypes?: VariantDocumentType[];
+    /** Images only; absent when unknown. */
+    height?: number;
+    /** Images only; absent when unknown. */
+    imageRole?: VariantImageRole;
+    kind: VariantAssetKind;
+    /** Not on images; absent when unknown. */
+    name?: string;
+    /** Images only; absent when unknown. */
+    presentation?: VariantImagePresentation;
+    url?: string;
+    /** Images only; absent when unknown. */
+    width?: number;
 };
-export type MaterialAssetProjectionDownload = {
-    ordinal: number;
-    url: string;
-    label: string | null;
-    assetKind: string;
-    status: string;
-    contentType: string | null;
-    fileExtension: string | null;
-    filename: string | null;
+/** Whether the maker's document source was read for this variant. Absent when documents are filtered out. */
+export type VariantDocumentCoverageState = OpenEnum<"available" | "none_declared" | "not_ingested" | "unavailable_source" | "dead_link" | "failed_ingest">;
+export type VariantAssetPageInfo = {
+    nextCursor: string | null;
+    returnedCount: number;
+    totalMatches: number;
+};
+/** Request filters and paging for `listVariantAssets`. Each list is OR within itself, AND across lists. */
+export type ListVariantAssetsOptions = {
+    kinds?: VariantAssetKind[];
+    imageRoles?: VariantImageRole[];
+    documentTypes?: VariantDocumentType[];
+    /** 1..50, default 20. */
+    limit?: number;
+    /** `pageInfo.nextCursor` from the previous page, with the same variantId and filters. */
+    cursor?: string;
+};
+/** One page. An unknown variant is a 404, never a page. */
+export type VariantAssetPage = {
+    documentCoverage?: VariantDocumentCoverageState;
+    items: VariantAssetItem[];
+    pageInfo: VariantAssetPageInfo;
+    /** The variant's primary image. Absent when it has none. */
+    primaryAssetId?: string;
 };
 export type MaterialDocumentStatus = OpenEnum<"downloaded" | "linked_not_downloaded" | "unavailable_source" | "dead_link" | "failed_ingest">;
 export type MaterialDocumentCoverageState = OpenEnum<"available" | "none_declared" | "not_ingested" | "unavailable_source" | "dead_link" | "failed_ingest">;
@@ -106,20 +143,3 @@ export type MaterialDocumentPage = {
     totalDocuments: number;
     nextCursor: string | null;
 };
-/** Tallies over what this projection returned — never a claim about the brand's own library. */
-export type MaterialAssetProjectionSummary = {
-    imageCount: number;
-    downloadCount: number;
-    documentCount: number;
-    readableDocumentCount: number;
-    downloadedImageCount: number;
-};
-export type MaterialAssetProjection = {
-    /** Opaque — echoed from the request. */
-    variantId: VariantId;
-    images: MaterialAssetProjectionImage[];
-    downloads: MaterialAssetProjectionDownload[];
-    documents: MaterialDocumentProjectionItem[];
-    documentCoverage: MaterialDocumentCoverage;
-    summary: MaterialAssetProjectionSummary;
-};

package/material-block-types.d.ts

@@ -50,6 +50,8 @@ export type MaterialBlockProjectionField = {
     attributeId: string;
     label: string;
     value: MaterialBlockFieldValue;
+    /** The value dictionary's label for a single-term `value`. Absent when no label is on record; `value` stays the canonical token. */
+    displayValue?: string;
     unit?: string;
     status: MaterialBlockFieldStatus;
     /** Provenance supplied by the graph when a source-backed claim supports this field. */

package/material-composition-client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The MATERIAL COMPOSITION lens: what a product is made of, and how far the
+ * corpus that answers that question has got (MG-1969).
+ *
+ * Not `./composition-client.ts`, which wraps the slot pools a scheme composer
+ * outside MaterialGraph reads.
+ */
+import type { HttpTransport } from "./http-transport.js";
+import type { CompositionCorpusSummary } from "./material-composition-types.js";
+/**
+ * THE QUESTION: "which product types can we answer that question for yet?"
+ *
+ * Coverage per product type, counted in Live SKUs as well as in tuples. Read
+ * the SKU figure: one tuple can carry a hundred thousand SKUs or one, so a
+ * corpus that resolved every rare tuple and none of the common ones reads as
+ * good coverage counted by tuple.
+ *
+ * A type in `completeness.authoringQueue` has no bar set, which is never the
+ * same as a bar it missed. Requires the `mg:read` scope.
+ */
+export declare const compositionReport: (transport: HttpTransport, signal?: AbortSignal) => Promise<CompositionCorpusSummary>;

package/material-composition-client.js

@@ -0,0 +1,13 @@
+import { resolveOperation } from "./operations.js";
+/**
+ * THE QUESTION: "which product types can we answer that question for yet?"
+ *
+ * Coverage per product type, counted in Live SKUs as well as in tuples. Read
+ * the SKU figure: one tuple can carry a hundred thousand SKUs or one, so a
+ * corpus that resolved every rare tuple and none of the common ones reads as
+ * good coverage counted by tuple.
+ *
+ * A type in `completeness.authoringQueue` has no bar set, which is never the
+ * same as a bar it missed. Requires the `mg:read` scope.
+ */
+export const compositionReport = async (transport, signal) => await transport.requestJson(resolveOperation("get_composition_report"), { signal });

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;
+};