@instruments/materialgraph 1.2.0 → 1.4.0

package/client.d.ts

@@ -4,6 +4,7 @@ import { CatalogClient } from "./catalog-client.js";
 import { CategoriesClient } from "./categories-client.js";
 import type { MaterialGraphClientOptions } from "./client-config.js";
 import { ColorsClient } from "./colors-client.js";
+import type { DiscoveryReference, DiscoveryTerms, InterpretDiscoveryTermsInput, ColorlessVariantsResult, VariantSibling } from "./discovery-context-types.js";
 import type { RateLimit } from "./errors.js";
 import type { FindSampledTogetherInput, FindSampledTogetherOutput } from "./find-sampled-together-types.js";
 import type { FindVariantsByColorInput, FindVariantsByColorOutput } from "./find-variants-by-color-types.js";
@@ -98,6 +99,14 @@ export declare class MaterialGraphClient extends CatalogClient {
     readonly workflows: WorkflowsClient;
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
+    /** Registry definitions and MG's catalog admission policy. */
+    discoveryReference(signal?: AbortSignal): Promise<DiscoveryReference>;
+    /** MG's exact category and generic color phrase readings. */
+    interpretDiscoveryTerms(input: InterpretDiscoveryTermsInput, signal?: AbortSignal): Promise<DiscoveryTerms>;
+    /** Colorless finishes among at most 250 supplied variants. */
+    colorlessVariants(variantIds: readonly string[], signal?: AbortSignal): Promise<ColorlessVariantsResult>;
+    /** The eligible colorways of this variant's product, in name/id order, capped at 300. */
+    variantSiblings(variantId: string, signal?: AbortSignal): Promise<VariantSibling[] | null>;
     /** Current catalog generation; authenticated, no SQL and no rate-limit charge. */
     getCatalogGeneration(signal?: AbortSignal): Promise<{
         generation: number;

package/client.js

@@ -129,6 +129,24 @@ export class MaterialGraphClient extends CatalogClient {
             signal,
         });
     }
+    /** Registry definitions and MG's catalog admission policy. */
+    async discoveryReference(signal) {
+        return await this.#get("get_discovery_reference", undefined, signal);
+    }
+    /** MG's exact category and generic color phrase readings. */
+    async interpretDiscoveryTerms(input, signal) {
+        return await this.#post("interpret_discovery_terms", input, signal);
+    }
+    /** Colorless finishes among at most 250 supplied variants. */
+    async colorlessVariants(variantIds, signal) {
+        return await this.#post("find_colorless_variants", { variantIds }, signal);
+    }
+    /** The eligible colorways of this variant's product, in name/id order, capped at 300. */
+    async variantSiblings(variantId, signal) {
+        return await this.#get("list_variant_siblings", undefined, signal, {
+            variantId,
+        });
+    }
     /** Current catalog generation; authenticated, no SQL and no rate-limit charge. */
     async getCatalogGeneration(signal) {
         return await this.#get("get_catalog_generation", undefined, signal);

package/discovery-context-types.d.ts

@@ -0,0 +1,45 @@
+import type { MaterialTile } from "./material-types.js";
+/** Static registry definitions and MG-owned discovery policy, without product counts. */
+export type DiscoveryReference = {
+    attributes: {
+        id: string;
+        name: string;
+        valueKind: string;
+        dictionaryId: string | null;
+        unit: string | null;
+        isArray: boolean;
+        filterable: boolean;
+    }[];
+    categories: {
+        id: string;
+        name: string;
+        path: string;
+        ancestorIds: string[];
+        inCatalog: boolean;
+    }[];
+    productTypes: {
+        id: string;
+        name: string;
+        description: string;
+    }[];
+    admittedBrandIds: string[];
+};
+export type InterpretDiscoveryTermsInput = {
+    text: string;
+    categoryIds: readonly string[];
+};
+export type DiscoveryTerms = {
+    categories: {
+        categoryIds: string[];
+        words: string[];
+    } | null;
+    colorWordHexes: string[];
+};
+export type ColorlessVariantsResult = {
+    variantIds: string[];
+};
+/** A sibling uses the same tile contract as the catalog's material cards. */
+export type VariantSibling = MaterialTile & {
+    distinction?: string;
+    distinguishedBy?: "size" | "code";
+};

package/discovery-context-types.js

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

package/find-sampled-together-types.d.ts

@@ -48,6 +48,8 @@ export type FindSampledTogetherRow = {
         proportion: number;
     }[];
     variantId: string;
+    /** The trimmed source variant label; null when unknown or for a paint color sample. Separate from surface finish, color family and derived color names. */
+    variantLabel: string | null;
     variantName: string | null;
 };
 export type FindSampledTogetherOutput = {
@@ -63,6 +65,8 @@ export type FindSampledTogetherOutput = {
         /** The id or name this seed came from. */
         resolvedFrom: string;
         variantId: string;
+        /** The trimmed source variant label; null when unknown or for a paint color sample. Separate from surface finish, color family and derived color names. */
+        variantLabel: string | null;
         variantName: string | null;
     }[];
     /** Seed ids outside the materials catalog; present only when at least one was. */

package/find-variants-by-color-types.d.ts

@@ -91,6 +91,8 @@ export type UnresolvedColor = {
     input: string | null;
 };
 export type ColorVariantMatch = {
+    /** The trimmed source variant label; null when unknown or for a paint color sample. Separate from surface finish, color family and derived color names. */
+    variantLabel: string | null;
     productType: {
         id: string;
         name: string;
@@ -156,6 +158,8 @@ export type ColorRankedSeed = {
 };
 /** RERANK's own card — the same shape `ColorVariantMatch` above (`brandId`, `code`), plus its perceptual distance. */
 export type ColorRankMatch = {
+    /** The trimmed source variant label; null when unknown or for a paint color sample. Separate from surface finish, color family and derived color names. */
+    variantLabel: string | null;
     brand: string;
     brandId: string;
     code: string | null;

package/get-variant-types.d.ts

@@ -94,7 +94,7 @@ export type GetVariantOutput = {
     /** The variant's Material Bank SKU. Absent means none is recorded. */
     materialBankId?: string;
     name: string;
-    /** The trimmed source variant label; null when unknown. Separate from surface finish and derived color names. */
+    /** The trimmed source variant label; null when unknown or for a paint color sample, whose own name identifies its color. Separate from surface finish, color family and derived color names. */
     variantLabel: string | null;
     /** Requested blocks or attributes the variant's product type does not carry. */
     notApplicable?: ListVariantsNotApplicable;

package/index.d.ts

@@ -1,3 +1,4 @@
+export type { DiscoveryReference, DiscoveryTerms, InterpretDiscoveryTermsInput, ColorlessVariantsResult, VariantSibling, } from "./discovery-context-types.js";
 export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
 export type { MaterialGraphClientOptions } from "./client.js";
 export type { FilterOp, FilterTermCondition, FilterNumericCondition, FilterPresenceCondition, FilterAnyFieldCondition, FilterCondition, FilterGroups, OptionalFilterGroups, OrderByEntry, ListVariantsInclude, ListVariantsCollapse, ColorRegion, ColorRangeCondition, ListVariantsInput, ListVariantsPreference, ListVariantsSpecifications, ListVariantsNotApplicable, SampleSubject, ListVariantsItem, ListVariantsOutput, VariantCard, } from "./list-variants-types.js";

package/list-variants-types.d.ts

@@ -207,7 +207,7 @@ export type ListVariantsItem = {
     /** The variant's Material Bank SKU. Absent means none is recorded. */
     materialBankId?: string;
     name: string;
-    /** The trimmed source variant label; null when unknown. Separate from surface finish and derived color names. */
+    /** The trimmed source variant label; null when unknown or for a paint color sample, whose own name identifies its color. Separate from surface finish, color family and derived color names. */
     variantLabel: string | null;
     notApplicable?: ListVariantsNotApplicable;
     preference?: ListVariantsPreference;

package/operation-responses.d.ts

@@ -4,6 +4,7 @@ import type { ListBrandsPage } from "./brand-types.js";
 import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogChannelCollectionsResponse, CatalogDocumentAccessResult, CatalogPageRepresentationReadResult, CatalogReferenceBatchResponse } from "./catalog-types.js";
 import type { CategoriesGetResult, CategoriesListResult } from "./category-types.js";
 import type { CategoryColorProfilesResponse } from "./color-profiles-types.js";
+import type { DiscoveryReference, DiscoveryTerms, ColorlessVariantsResult, VariantSibling } from "./discovery-context-types.js";
 import type { FindSampledTogetherOutput } from "./find-sampled-together-types.js";
 import type { FindVariantsByColorOutput } from "./find-variants-by-color-types.js";
 import type { FindVariantsByVectorOutput } from "./find-variants-by-vector-types.js";
@@ -22,6 +23,10 @@ import type { SchemaResourceResponse } from "./schema-resource-types.js";
 import type { SearchVariantsOutput } from "./search-variants-types.js";
 import type { ExtractPaletteResponse, ListAttributesResult, PairingsResponse, ResolveColorResponse, WhoamiResponse } from "./types.js";
 export type OperationResponses = {
+    get_discovery_reference: DiscoveryReference;
+    interpret_discovery_terms: DiscoveryTerms;
+    find_colorless_variants: ColorlessVariantsResult;
+    list_variant_siblings: VariantSibling[] | null;
     find_nearest_paints: NearestPaintsOutput;
     get_catalog_generation: {
         generation: number;

package/operations.generated.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.8.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["colors.nearestPaints", "GET", "/api/v1/colors/nearest-paints", "find_nearest_paints"], readonly ["getCatalogGeneration", "GET", "/api/v1/catalog/generation", "get_catalog_generation"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["samplizeCatalog", "GET", "/api/v1/catalogs/samplize/products", "samplize_catalog_products"], readonly ["catalogReferencesForVariants", "POST", "/api/v1/catalogs/references", "get_catalog_references_batch"], readonly ["catalogCollections", "GET", "/api/v1/catalogs/collections", "list_catalog_channel_collections"], readonly ["catalogDocumentAccess", "GET", "/api/v1/catalogs/documents/{documentId}", "get_catalog_document_access"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColor", "GET", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findSampledTogether", "GET", "/api/v1/variants/sampled-together", "find_sampled_together"], readonly ["listSampledTogetherPairs", "GET", "/api/v1/variants/sampled-together/pairs", "list_sampled_together_pairs"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColor", "GET", "/api/v1/search/colors/resolve", "resolve_color_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colors.profiles", "GET", "/api/v1/colors/profiles", "get_category_color_profiles"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["workflows.start", "POST", "/api/v1/workflows/{workflowId}/runs", "create_public_run"], readonly ["workflows.run", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}", "get_public_run"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
+declare const OPERATION_DEFINITIONS: readonly [readonly ["discoveryReference", "GET", "/api/v1/catalog/discovery-reference", "get_discovery_reference"], readonly ["interpretDiscoveryTerms", "POST", "/api/v1/catalog/interpret-terms", "interpret_discovery_terms"], readonly ["colorlessVariants", "POST", "/api/v1/variants/colorless", "find_colorless_variants"], readonly ["variantSiblings", "GET", "/api/v1/variants/{variantId}/siblings", "list_variant_siblings"], readonly ["colors.nearestPaints", "GET", "/api/v1/colors/nearest-paints", "find_nearest_paints"], readonly ["getCatalogGeneration", "GET", "/api/v1/catalog/generation", "get_catalog_generation"], readonly ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"], readonly ["catalogPages", "GET", "/api/v1/catalogs/{catalogId}/pages", "list_catalog_pages"], readonly ["catalogPageRepresentation", "GET", "/api/v1/catalog-pages/{pageId}/representation", "get_catalog_page_representation"], readonly ["catalogReferences", "GET", "/api/v1/catalogs/{catalogId}/references", "list_catalog_product_references"], readonly ["samplizeCatalog", "GET", "/api/v1/catalogs/samplize/products", "samplize_catalog_products"], readonly ["catalogReferencesForVariants", "POST", "/api/v1/catalogs/references", "get_catalog_references_batch"], readonly ["catalogCollections", "GET", "/api/v1/catalogs/collections", "list_catalog_channel_collections"], readonly ["catalogDocumentAccess", "GET", "/api/v1/catalogs/documents/{documentId}", "get_catalog_document_access"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["listVariantAssets", "GET", "/api/v1/variants/{variantId}/assets", "list_variant_assets"], readonly ["materialDocuments", "GET", "/api/v1/materials/{variantId}/documents", "list_material_documents"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["associatedFinishes", "GET", "/api/v1/associated/finishes", "list_associated_finishes"], readonly ["associatedProducts", "GET", "/api/v1/associated/products", "list_associated_products"], readonly ["applicability", "GET", "/api/v1/applicability", "get_applicability"], readonly ["listVariants", "GET", "/api/v1/variants", "list_variants"], readonly ["listVariantFacets", "POST", "/api/v1/variants/facets", "list_variant_facets"], readonly ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"], readonly ["findVariantsByColor", "GET", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findSampledTogether", "GET", "/api/v1/variants/sampled-together", "find_sampled_together"], readonly ["listSampledTogetherPairs", "GET", "/api/v1/variants/sampled-together/pairs", "list_sampled_together_pairs"], readonly ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"], readonly ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"], readonly ["resolveColor", "GET", "/api/v1/search/colors/resolve", "resolve_color_name"], readonly ["listAttributes", "GET", "/api/v1/catalog/attributes", "catalog_list_attributes"], readonly ["listEnumValues", "GET", "/api/v1/catalog/enum-values", "catalog_list_enum_values"], readonly ["categories.list", "GET", "/api/v1/categories", "list_categories"], readonly ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["colors.profiles", "GET", "/api/v1/colors/profiles", "get_category_color_profiles"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["workflows.start", "POST", "/api/v1/workflows/{workflowId}/runs", "create_public_run"], readonly ["workflows.run", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}", "get_public_run"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation<K extends SdkOperationId = SdkOperationId> = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.generated.js

@@ -1,6 +1,30 @@
 // GENERATED by apps/web/scripts/generate-openapi-v1.ts. Do not edit.
 export const MATERIALGRAPH_API_VERSION = "0.8.0";
 const OPERATION_DEFINITIONS = [
+    [
+        "discoveryReference",
+        "GET",
+        "/api/v1/catalog/discovery-reference",
+        "get_discovery_reference",
+    ],
+    [
+        "interpretDiscoveryTerms",
+        "POST",
+        "/api/v1/catalog/interpret-terms",
+        "interpret_discovery_terms",
+    ],
+    [
+        "colorlessVariants",
+        "POST",
+        "/api/v1/variants/colorless",
+        "find_colorless_variants",
+    ],
+    [
+        "variantSiblings",
+        "GET",
+        "/api/v1/variants/{variantId}/siblings",
+        "list_variant_siblings",
+    ],
     [
         "colors.nearestPaints",
         "GET",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "exports": {
     ".": {

package/response-schemas.generated.d.ts

@@ -1,5 +1,5 @@
 /** The API contract version the schemas were generated from. */
 export declare const RESPONSE_SCHEMA_API_VERSION = "0.8.0";
 /** Every SDK operation whose success response has a published JSON Schema. */
-export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["find_nearest_paints", "get_catalog_generation", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "samplize_catalog_products", "get_catalog_references_batch", "list_catalog_channel_collections", "get_catalog_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_sampled_together", "list_sampled_together_pairs", "resolve_variant", "get_variant", "resolve_color_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "get_category_color_profiles", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run"];
+export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["get_discovery_reference", "interpret_discovery_terms", "find_colorless_variants", "list_variant_siblings", "find_nearest_paints", "get_catalog_generation", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "samplize_catalog_products", "get_catalog_references_batch", "list_catalog_channel_collections", "get_catalog_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_sampled_together", "list_sampled_together_pairs", "resolve_variant", "get_variant", "resolve_color_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "get_category_color_profiles", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run"];
 export declare const RESPONSE_SCHEMA_CATALOG_JSON: string;