@instruments/materialgraph 0.17.0 → 0.19.0

package/association-types.d.ts

@@ -11,6 +11,7 @@
  * Present them as separate sections, and never describe a pairing as available.
  */
 import type { Cursor, VariantId } from "./identifiers.js";
+import type { ProductTypeReceipt } from "./material-types.js";
 /**
  * Why an association is believed.
  *
@@ -42,8 +43,16 @@ export interface DeclaredAssociation {
     brand: string;
     product: string;
     variantName: string | null;
+    /** The role played by this endpoint of the declared edge. */
+    role: "finish" | "product";
+    /** The directed relationship asserted by the manufacturer. */
+    relation: "applicable_finish";
+    /** Accepted sampleability when known; absent means unknown. */
+    sampleable?: boolean;
     /** Canonical thumbnail; null when the variant has no eligible image. */
     imageUrl: string | null;
+    /** Review receipt; proposed types are never accepted categories. */
+    productTypeReceipt: ProductTypeReceipt;
     declared: DeclaredProvenance;
 }
 /**
@@ -77,12 +86,13 @@ export interface AssociatedOptions {
      */
     limit?: number;
     /**
-     * Orderability scope. `material_bank` returns only associations pointing at a
-     * variant carrying a Material Bank SKU — the ones a caller can actually
-     * order. Today every visible variant carries one, so this currently removes
-     * nothing; it tracks orderability rather than a snapshot of it.
+     * Source identity scope. `material_bank` returns associations pointing at a
+     * variant carrying a Material Bank SKU. A SKU alone does not establish current
+     * sampleability; use `sampleableOnly` for an accepted availability fact.
      */
     corpus?: "all" | "material_bank";
+    /** Return only associations whose effective sampleability is true. */
+    sampleableOnly?: boolean;
     /**
      * The previous response's `nextCursor`, passed back verbatim. A cursor is
      * bound to its subject, direction and corpus — replaying it against a
@@ -90,3 +100,79 @@ export interface AssociatedOptions {
      */
     cursor?: Cursor;
 }
+export type ApplicabilitySubject = {
+    kind: "product";
+    id: string;
+} | {
+    kind: "variant";
+    id: VariantId;
+};
+export type ApplicabilityCoverageState = "available" | "partial" | "none_declared" | "not_ingested" | "source_not_applicable" | "unavailable";
+export interface ApplicabilityCoverage {
+    state: ApplicabilityCoverageState;
+    countKind: "exact" | "partial";
+    declaredCount: number | null;
+    sourceAuthority: string;
+    sourceLocator: string;
+    sourceRevision: string;
+}
+export interface ApplicabilityFact {
+    id: string;
+    subject: ApplicabilitySubject;
+    finish: {
+        kind: "variant";
+        id: VariantId;
+    };
+    relation: "applicable_finish";
+    evidenceScope: "manufacturer_declared";
+    declaringBrandId: string;
+    source: {
+        authority: string;
+        locator: string;
+        revision: string;
+    };
+    lifecycle: "active";
+}
+export interface ApplicabilitySourceEntry {
+    scope: {
+        sourceAuthority: string;
+        sourceLocator: string;
+    };
+    /** Null when facts exist but this direction has no coverage census. */
+    coverage: ApplicabilityCoverage | null;
+    /** Revisions carried by active facts, independent from the coverage revision. */
+    factRevisions: string[];
+    /** Active facts from this source only. */
+    facts: ApplicabilityFact[];
+    /** Source endpoints that could not be resolved during reconciliation. */
+    unresolved: UnresolvedApplicabilityEndpoint[];
+}
+export interface UnresolvedApplicabilityEndpoint {
+    subjectLocator: string;
+    subjectKind: "product" | "variant" | "unknown";
+    finishLocator: string;
+    finishKind: "variant" | "unknown";
+    reason: "subject_unresolved" | "finish_unresolved" | "both_unresolved" | "unsupported_subject_kind";
+    declaringBrandId: string | null;
+    source: {
+        authority: string;
+        locator: string;
+        revision: string;
+    };
+}
+/** Source-grained response; sources are never merged or given hidden precedence. */
+export interface ApplicabilityResponse {
+    kind: "manufacturer_declared_applicability";
+    requestedSubject: ApplicabilitySubject;
+    direction: "forward" | "reverse";
+    sources: ApplicabilitySourceEntry[];
+}
+export type ApplicabilityOptions = {
+    subjectKind: "product";
+    subjectId: string;
+    direction: "forward";
+} | {
+    subjectKind: "variant";
+    subjectId: VariantId;
+    direction: "forward" | "reverse";
+};

package/associations-client.d.ts

@@ -12,7 +12,7 @@
  * sections, never concatenate them, and never describe a pairing as
  * "available on".
  */
-import type { AssociatedOptions, DeclaredAssociationsResponse } from "./association-types.js";
+import type { ApplicabilityOptions, ApplicabilityResponse, AssociatedOptions, DeclaredAssociationsResponse } from "./association-types.js";
 import { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
 /**
@@ -49,3 +49,5 @@ export declare function declaredFinishes(transport: HttpTransport, variantId: Va
  * @param variantId The FINISH variant. Opaque — pass back exactly what you were given.
  */
 export declare function declaredProducts(transport: HttpTransport, variantId: VariantId, options?: AssociatedOptions, signal?: AbortSignal): Promise<DeclaredAssociationsResponse>;
+/** Read manufacturer-declared applicability without collapsing Product/Variant grain. */
+export declare function applicability(transport: HttpTransport, options: ApplicabilityOptions, signal?: AbortSignal): Promise<ApplicabilityResponse>;

package/associations-client.js

@@ -38,3 +38,7 @@ export function declaredFinishes(transport, variantId, options, signal) {
 export function declaredProducts(transport, variantId, options, signal) {
     return transport.requestJson(resolveOperation("list_associated_products"), { query: { variantId, ...options }, signal });
 }
+/** Read manufacturer-declared applicability without collapsing Product/Variant grain. */
+export function applicability(transport, options, signal) {
+    return transport.requestJson(resolveOperation("get_applicability"), { query: options, signal });
+}

package/browse-types.d.ts

@@ -26,6 +26,8 @@ export interface BrowseResultItem {
     productId: ProductId | null;
     color: string | null;
     variantName: string | null;
+    /** MaterialGraph record creation time, not a manufacturer release date. */
+    recordCreatedAt: string | null;
     imageUrl: string | null;
     scalars: {
         l: number | null;
@@ -165,11 +167,20 @@ export interface BrowseParams {
      */
     types?: string;
     /**
-     * Comma-separated brand slugs (`farrow-ball`) or display names
-     * (`Farrow & Ball`), case-insensitive. One brand plus a colour `sort` is that
-     * brand's fan deck. An unknown brand is a 400 naming it, never an empty page.
+     * Comma-separated canonical brand ids, exact slugs (`farrow-ball`), or exact
+     * display names (`Farrow & Ball`). Canonical ids and slugs are case-sensitive
+     * and opaque; display names are case-insensitive. One brand plus a colour `sort` is that brand's
+     * fan deck. An unknown brand is a typed 400 naming it, and an exact display
+     * name shared by multiple brands is a typed 400 with the candidates; neither
+     * becomes an empty page.
      */
     brands?: string;
+    /**
+     * Positive manufacturer declarations. accepts_finishes includes variants of
+     * product-level declarations; it does not assert variant-specific applicability.
+     * Absence means no role filter.
+     */
+    role?: "finish" | "accepts_finishes";
     /**
      * Typed attribute filters, in the SAME grammar `search` takes — a term, a
      * term SET (OR within the entry), a presence check or a numeric range, each

package/by-colour-types.d.ts

@@ -169,12 +169,17 @@ export interface ByColourResponse {
         colours: string[];
         categories?: string[];
         /**
-         * Echoed brand filter as resolved SLUGS — what the names you passed
-         * resolved to. Present only when a brand scope applied.
+         * Echoed brand filter as resolved SLUGS — what the canonical ids, slugs,
+         * or exact names you passed resolved to. Present only when a brand scope
+         * applied.
          */
         brands?: string[];
         /** Echoed `family` filter, normalised. Present only when one was applied. */
         family?: string;
+        /** Applied single-colour containment order. */
+        order?: "representative" | "nearest";
+        /** Applied maximum OKLab distance to each reported match hex. */
+        maxColourDistance?: number;
         oklab?: OklabTriple;
     };
     /** `matches.length` — THIS PAGE. Not a corpus total; this surface states none. */
@@ -186,6 +191,12 @@ export interface ByColourResponse {
      * what says so in counts rather than adjectives.
      */
     familyGate?: ColourFamilyGate;
+    /** Applied `maxColourDistance` threshold and its page-bounded drop count. */
+    proximityGate?: {
+        maxColourDistance: number;
+        considered: number;
+        dropped: number;
+    };
     /**
      * Present only when `category` was asked for. It states that variants without
      * an accepted primary product type were excluded by the hard gate; absence
@@ -230,8 +241,10 @@ export interface ByColourParams {
     /** HARD category filter — display names or taxonomy ids (repeatable). */
     category?: string | string[];
     /**
-     * HARD brand filter (repeatable) — a brand SLUG (`sherwin-williams`) or its
-     * display name (`Sherwin-Williams`), case-insensitive.
+     * HARD brand filter (repeatable) — a canonical brand id, exact brand SLUG
+     * (`sherwin-williams`), or exact display name (`Sherwin-Williams`). Canonical
+     * ids and slugs are case-sensitive and opaque; display names are
+     * case-insensitive.
      *
      * This is how the CROSS-BRAND question is asked: pass one brand's colour as
      * `hex` and scope to another to get that brand's nearest colours to it. It is
@@ -239,8 +252,9 @@ export interface ByColourParams {
      * filtering a returned page instead comes back short, because a
      * nearest-neighbour scan does not know to look further.
      *
-     * An unknown brand is a 400 naming it, never an empty page. Omitting it (or
-     * passing an empty list) searches every brand.
+     * An unknown brand is a typed 400 naming it, and an exact display name shared
+     * by multiple brands is a typed 400 with the candidates; neither becomes an
+     * empty page. Omitting it (or passing an empty list) searches every brand.
      */
     brand?: string | string[];
     /**
@@ -260,6 +274,10 @@ export interface ByColourParams {
      * drop.
      */
     family?: string;
+    /** Single-colour order; omitted keeps representative browsing order. */
+    order?: "representative" | "nearest";
+    /** Maximum OKLab distance to each match's reported hex. Single-colour only. */
+    maxColourDistance?: number;
     /** Narrow retrieval inside the server query; absent means the whole graph. */
     corpusScope?: CorpusScope;
     limit?: number;

package/by-spec-types.d.ts

@@ -1,4 +1,5 @@
 import type { ValueResolution } from "./catalog-discovery-types.js";
+import type { VerdictCitation } from "./citation-types.js";
 import type { VariantId } from "./identifiers.js";
 /**
  * One criterion a match satisfied, with the trust behind it.
@@ -71,6 +72,7 @@ export interface BySpecVerdictCell {
      *  - `proposed` — the value is awaiting acceptance and is not yet on record.
      */
     trustGap: "below_confidence" | "basis_unmet" | "proposed" | null;
+    citation?: VerdictCitation;
 }
 /**
  * A match's full report card: every cell, the rolled-up grade, weakest confidence.
@@ -131,6 +133,8 @@ export interface BySpecUnresolvedCriterion {
     attributeId: string;
     /** The parsed value — never overwritten by the attribute id when that id is unknown. */
     value: string;
+    /** Why pre-flight declined it; absent on responses captured before classification. */
+    reason?: "unknown_attribute_or_term" | "not_a_specification";
     /** Ranked candidates for whichever half failed. See {@link ValueResolution}. */
     resolution: ValueResolution;
 }

package/catalogue-client.d.ts

@@ -1,10 +1,13 @@
-import type { CatalogDocumentList, CatalogProductReferenceList, CatalogueDocumentAccessResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
+import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueCollectionsOptions, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
+import type { SamplizeCatalogueOptions, SamplizeCataloguePage } from "./samplize-catalogue-types.js";
 /** Catalogue publication operations inherited by the public SDK client. */
 export declare class CatalogueClient {
     #private;
     protected constructor(transport: HttpTransport);
+    /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
+    samplizeCatalogue(options?: SamplizeCatalogueOptions, signal?: AbortSignal): Promise<SamplizeCataloguePage>;
     /**
      * Read exact, verified brand-publication page relationships for variants.
      * Missing evidence stays explicit; this operation never guesses a page from
@@ -13,10 +16,19 @@ export declare class CatalogueClient {
     catalogueReferences(input: {
         variantIds: VariantId[];
     }, signal?: AbortSignal): Promise<CatalogueReferenceBatchResponse>;
+    /** List product collections with governed catalogue-channel membership. */
+    catalogueCollections(options?: CatalogueCollectionsOptions, signal?: AbortSignal): Promise<CatalogueChannelCollectionsResponse>;
     /** List immutable catalog documents retained from verified source material. */
     catalogs(signal?: AbortSignal): Promise<CatalogDocumentList>;
+    /** List stable one-based page identities and their representation status. */
+    catalogPages(catalogId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }, signal?: AbortSignal): Promise<CatalogPageListResult>;
+    /** Read a retained page representation or its exact missing-artifact receipt. */
+    catalogPageRepresentation(pageId: string, signal?: AbortSignal): Promise<CataloguePageRepresentationReadResult>;
     /** Read every verified product/page reference for one retained catalog. */
-    catalogReferences(catalogId: string, signal?: AbortSignal): Promise<CatalogProductReferenceList>;
+    catalogReferences(catalogId: string, signal?: AbortSignal): Promise<CatalogProductReferenceReadResult>;
     /** Resolve browser-safe access to one immutable catalogue document. */
     catalogueDocumentAccess(documentId: string, signal?: AbortSignal): Promise<CatalogueDocumentAccessResult>;
 }

package/catalogue-client.js

@@ -5,6 +5,10 @@ export class CatalogueClient {
     constructor(transport) {
         this.#transport = transport;
     }
+    /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
+    samplizeCatalogue(options = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("samplize_catalogue_products"), { query: { ...options }, signal });
+    }
     /**
      * Read exact, verified brand-publication page relationships for variants.
      * Missing evidence stays explicit; this operation never guesses a page from
@@ -13,10 +17,29 @@ export class CatalogueClient {
     catalogueReferences(input, signal) {
         return this.#transport.requestJson(resolveOperation("get_catalogue_references_batch"), { body: input, signal });
     }
+    /** List product collections with governed catalogue-channel membership. */
+    catalogueCollections(options = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("list_catalogue_channel_collections"), {
+            query: {
+                limit: options.limit,
+                offset: options.offset,
+                sampleLimit: options.sampleLimit,
+            },
+            signal,
+        });
+    }
     /** List immutable catalog documents retained from verified source material. */
     catalogs(signal) {
         return this.#transport.requestJson(resolveOperation("list_catalog_documents"), { signal });
     }
+    /** List stable one-based page identities and their representation status. */
+    catalogPages(catalogId, options = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("list_catalog_pages"), { pathParams: { catalogId }, query: options, signal });
+    }
+    /** Read a retained page representation or its exact missing-artifact receipt. */
+    catalogPageRepresentation(pageId, signal) {
+        return this.#transport.requestJson(resolveOperation("get_catalog_page_representation"), { pathParams: { pageId }, signal });
+    }
     /** Read every verified product/page reference for one retained catalog. */
     catalogReferences(catalogId, signal) {
         return this.#transport.requestJson(resolveOperation("list_catalog_product_references"), { pathParams: { catalogId }, signal });