@instruments/materialgraph 0.25.0 → 0.27.0

package/material-asset-types.d.ts

@@ -1,57 +1,94 @@
 /**
- * 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 interface MaterialAssetProjectionImage {
-    key: string;
-    ordinal: number;
-    proxyPath: string;
-    visualRole: MaterialAssetVisualRole;
-    status: MaterialAssetStatus;
-    contentType: string | null;
-    fileExtension: string | null;
-    filename: string | null;
-    byteSize: number | null;
-}
-export interface MaterialAssetProjectionDownload {
-    ordinal: number;
-    url: string;
-    label: string | null;
-    assetKind: string;
-    status: string;
-    contentType: string | null;
-    fileExtension: string | null;
-    filename: string | 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;
+};
+/** 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">;
-export interface MaterialDocumentScope {
+export type MaterialDocumentScope = {
     kind: "product" | "variant";
     id: string;
-}
-export interface MaterialDocumentSource {
+};
+export type MaterialDocumentSource = {
     /** Opaque, public identifier for one source collection; never a PIM/DAM path. */
     id: string;
     authority: string;
     revision: string;
-}
-export interface MaterialDocumentProjectionItem {
+};
+export type MaterialDocumentProjectionItem = {
     id: string;
     scope: MaterialDocumentScope & {
         inherited: boolean;
@@ -61,12 +98,12 @@ export interface MaterialDocumentProjectionItem {
     /** True only for a Product declaration or this exact requested Variant. */
     appliesToRequestedVariant: boolean;
     /** Every exact source-grain declaration collapsed into this URL identity. */
-    declarations: Array<{
+    declarations: {
         scope: MaterialDocumentScope;
         source: MaterialDocumentSource;
         status: MaterialDocumentStatus;
         readable: boolean;
-    }>;
+    }[];
     documentType: string | null;
     originalName: string;
     status: MaterialDocumentStatus;
@@ -75,51 +112,34 @@ export interface MaterialDocumentProjectionItem {
     contentType: string | null;
     fileExtension: string | null;
     source: MaterialDocumentSource;
-}
-export interface MaterialDocumentCoverageSource {
+};
+export type MaterialDocumentCoverageSource = {
     scope: MaterialDocumentScope;
     state: MaterialDocumentCoverageState;
     exact: boolean;
     declaredCount: number | null;
     readableCount: number;
     source: MaterialDocumentSource;
-}
-export interface MaterialDocumentCoverage {
+};
+export type MaterialDocumentCoverage = {
     productUnion: MaterialDocumentCoverageSummary;
     requestedVariant: MaterialDocumentCoverageSummary;
     sources: MaterialDocumentCoverageSource[];
-}
-export interface MaterialDocumentCoverageSummary {
+};
+export type MaterialDocumentCoverageSummary = {
     state: MaterialDocumentCoverageState;
     exact: boolean;
     declaredCount: number | null;
     readableCount: number;
-}
-export interface MaterialDocumentPageOptions {
+};
+export type MaterialDocumentPageOptions = {
     cursor?: string;
     limit?: number;
-}
-export interface MaterialDocumentPage {
+};
+export type MaterialDocumentPage = {
     variantId: VariantId;
     documents: MaterialDocumentProjectionItem[];
     coverage: MaterialDocumentCoverage;
     totalDocuments: number;
     nextCursor: string | null;
-}
-/** Tallies over what this projection returned — never a claim about the brand's own library. */
-export interface MaterialAssetProjectionSummary {
-    imageCount: number;
-    downloadCount: number;
-    documentCount: number;
-    readableDocumentCount: number;
-    downloadedImageCount: number;
-}
-export interface MaterialAssetProjection {
-    /** Opaque — echoed from the request. */
-    variantId: VariantId;
-    images: MaterialAssetProjectionImage[];
-    downloads: MaterialAssetProjectionDownload[];
-    documents: MaterialDocumentProjectionItem[];
-    documentCoverage: MaterialDocumentCoverage;
-    summary: MaterialAssetProjectionSummary;
-}
+};

package/material-block-types.d.ts

@@ -45,32 +45,34 @@ export type MaterialBlockFieldValue = string | number | boolean | unknown[] | Re
  * `status: "verified"` is a real negative you may publish; the same `false`
  * under `missing` is a placeholder for an unanswered question.
  */
-export interface MaterialBlockProjectionField {
+export type MaterialBlockProjectionField = {
     /** Canonical vocabulary, not an opaque id — the same token `bySpec` accepts. */
     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. */
     sourceBasis?: string;
     /** Claim confidence supplied by the graph; absence means no confidence was emitted. */
     confidence?: number;
-}
-export interface MaterialBlockProjectionItem {
+};
+export type MaterialBlockProjectionItem = {
     canonicalBlockId: string;
     canonicalBlockName: string;
     status: MaterialBlockStatus;
     fields: MaterialBlockProjectionField[];
     /** The work queue: attributes with `status: "missing"`. UNKNOWN, never "none". */
     missingAttributeIds: string[];
-}
+};
 /**
  * Every canonical block for one material, each field carrying whether it is
  * determined. The whole surface, not a page — there is no cursor here.
  */
-export interface MaterialBlockProjection {
+export type MaterialBlockProjection = {
     /** Opaque — echoed from the request. */
     variantId: VariantId;
     blocks: MaterialBlockProjectionItem[];
-}
+};

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