@instruments/materialgraph 2.3.0 → 3.0.1

package/client.d.ts

@@ -1,6 +1,5 @@
 import type { ApplicabilityOptions, AssociatedOptions } from "./association-types.js";
 import type { BrandsOptions } from "./brand-types.js";
-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";
@@ -16,6 +15,7 @@ import type { ListSampledTogetherPairsInput, ListSampledTogetherPairsOutput } fr
 import type { ListVariantFacetsInput, ListVariantFacetsOutput } from "./list-variant-facets-types.js";
 import type { ListVariantsInput, ListVariantsOutput } from "./list-variants-types.js";
 import type { ListVariantAssetsOptions, MaterialDocumentPageOptions, VariantAssetPage } from "./material-asset-types.js";
+import type { ResolveVariantInput, ResolveVariantOutput } from "./resolve-variant-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
 import type { SearchVariantsInput, SearchVariantsOutput } from "./search-variants-types.js";
 import type { SourceMaterialBatchReceipt, UploadSourceMaterialInput } from "./source-material-types.js";
@@ -56,7 +56,7 @@ export type { MaterialGraphClientOptions } from "./client-config.js";
  * And three reading rules that apply to every lens: ids are opaque (see
  * `./identifiers.ts`), absent is not false, and a page is not a corpus.
  */
-export declare class MaterialGraphClient extends CatalogClient {
+export declare class MaterialGraphClient {
     #private;
     readonly baseUrl: string;
     /**
@@ -101,6 +101,18 @@ export declare class MaterialGraphClient extends CatalogClient {
     getCatalogGeneration(signal?: AbortSignal): Promise<{
         generation: number;
     }>;
+    /**
+     * THE QUESTION: "what does this brand page or code resolve to in the
+     * graph?" Give `input.url` alone, or `input.code` with `input.brandId` (from
+     * {@link MaterialGraphClient.brands}) when there is no page to read.
+     *
+     * Exact and scoreless: a sibling colorway, a similar image or a brand match
+     * alone never identifies a variant. Read `outcome` - `identified` names
+     * an exact stored variant, `placed` an exact brand with no variant match,
+     * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
+     * never a guess. The submitted URL is never persisted.
+     */
+    resolveVariant(input: ResolveVariantInput, signal?: AbortSignal): Promise<ResolveVariantOutput>;
     /**
      * THE QUESTION: "tell me about THIS variant" (GET
      * `/api/v1/variants/{variantId}`, `get_variant`).

package/client.js

@@ -1,6 +1,5 @@
 import { applicability, declaredFinishes, declaredProducts, } from "./associations-client.js";
 import { listBrands } from "./brands-client.js";
-import { CatalogClient } from "./catalog-client.js";
 import { CategoriesClient } from "./categories-client.js";
 import { DEFAULT_BASE_URL } from "./client-config.js";
 import { listAttributes as listAttributesCall, listEnumValues as listEnumValuesCall, resolveColor as resolveColorCall, } from "./client-vocabulary.js";
@@ -48,7 +47,7 @@ export { DEFAULT_BASE_URL } from "./client-config.js";
  * And three reading rules that apply to every lens: ids are opaque (see
  * `./identifiers.ts`), absent is not false, and a page is not a corpus.
  */
-export class MaterialGraphClient extends CatalogClient {
+export class MaterialGraphClient {
     baseUrl;
     /**
      * THE QUESTION: "what kinds of thing exist, and what are their keys?"
@@ -91,7 +90,6 @@ export class MaterialGraphClient extends CatalogClient {
                 ? {}
                 : { timeoutMs: options.timeoutMs }),
         });
-        super(transport);
         this.#transport = transport;
         this.baseUrl = transport.baseUrl;
         this.categories = new CategoriesClient({
@@ -140,6 +138,23 @@ export class MaterialGraphClient extends CatalogClient {
     async getCatalogGeneration(signal) {
         return await this.#get("get_catalog_generation", undefined, signal);
     }
+    /**
+     * THE QUESTION: "what does this brand page or code resolve to in the
+     * graph?" Give `input.url` alone, or `input.code` with `input.brandId` (from
+     * {@link MaterialGraphClient.brands}) when there is no page to read.
+     *
+     * Exact and scoreless: a sibling colorway, a similar image or a brand match
+     * alone never identifies a variant. Read `outcome` - `identified` names
+     * an exact stored variant, `placed` an exact brand with no variant match,
+     * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
+     * never a guess. The submitted URL is never persisted.
+     */
+    async resolveVariant(input, signal) {
+        return await this.#transport.requestJson(operation("resolve_variant"), {
+            body: input,
+            signal,
+        });
+    }
     // ── Materials ──────────────────────────────────────────────────────────────
     /**
      * THE QUESTION: "tell me about THIS variant" (GET

package/get-variant-types.d.ts

@@ -11,7 +11,7 @@ import type { ListVariantsNotApplicable, ListVariantsSpecifications, SampleSubje
 import type { VariantColorPalette } from "./material-block-types.js";
 /** The detail to add under `specifications`; absent, the answer is the compact item alone. */
 export type GetVariantOptions = {
-    /** Canonical attribute ids, e.g. `["nrc_rating"]`. */
+    /** Canonical attribute ids, e.g. `["nrc"]`. */
     attributes?: readonly string[];
     /** Canonical block ids, returned whole, e.g. `["acoustic"]`. */
     blocks?: readonly string[];

package/index.d.ts

@@ -20,7 +20,6 @@ export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type { OpenEnum, JsonValue, OklabTriple, MaterialColor, ImageSource, MaterialAvailability, MaterialTile, DemandMomentum, CompanionDemand, ProjectTypeShare, CospecPairing, ColorPairing, PairingOrderMode, PairingRanking, PairingOrdering, PairingItem, PairingsResponse, AttributeMatch, AttributeListItem, OutsideScopeAttribute, ListAttributesResult, WhoamiResponse, PairingsOptions, ListAttributesOptions, ExtractedPalette, ExtractPaletteResponse, ExtractPaletteInput, ResolveValueCandidate, ValueResolution, ResolveColorOptions, ResolveColorCatalogVariant, ResolveColorVariant, ResolveColorResponse, BySpecVerdictState, BySpecVerdictCell, BySpecVerdict, MaterialVerdict, BySpecUnresolvedCriterion, } from "./types.js";
 export type { ResolveVariantInput, ResolveVariantSubject, ResolveVariantEvidence, ResolveVariantReceipt, ResolveVariantUnresolvedReason, ResolveVariantOutput, } from "./resolve-variant-types.js";
-export type { CatalogReference, CatalogReferenceAbsenceReason, CatalogReferencePublication, CatalogReferenceResult, CatalogReferenceBatchResponse, CatalogDocumentAccess, CatalogDocumentAccessResult, CatalogDocument, CatalogEdition, CatalogAvailableReceipt, CatalogFailureReceipt, UnavailableCatalogDocument, CatalogPublication, CatalogDocumentList, CatalogProductReferenceList, CatalogProductReferenceUnavailable, CatalogProductReferenceReadResult, CatalogPageRequiredArtifact, CatalogPageAvailableArtifact, CatalogPage, CatalogPageListResult, CatalogPageRepresentationReadResult, } from "./catalog-types.js";
 export { CategoriesClient } from "./categories-client.js";
 export type { CategoryRef, CategoryKind, CategoryMatch, CategoryItem, CategoriesPageInfo, CategoriesListInput, CategoriesListResult, CategoryConcept, CategoryProductCategory, CategoriesGetResult, } from "./category-types.js";
 export { ColorsClient } from "./colors-client.js";

package/operation-responses.d.ts

@@ -1,7 +1,6 @@
 /** Response types belong to operation ids, never a caller-selected generic. */
 import type { ApplicabilityResponse, DeclaredAssociationsResponse } from "./association-types.js";
 import type { ListBrandsPage } from "./brand-types.js";
-import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, 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";
@@ -38,9 +37,6 @@ export type OperationResponses = {
     find_variants_by_color: FindVariantsByColorOutput;
     find_variants_by_vector: FindVariantsByVectorOutput;
     get_applicability: ApplicabilityResponse;
-    get_catalog_page_representation: CatalogPageRepresentationReadResult;
-    get_catalog_document_access: CatalogDocumentAccessResult;
-    get_catalog_references_batch: CatalogReferenceBatchResponse;
     get_category: CategoriesGetResult;
     get_category_color_profiles: CategoryColorProfilesResponse;
     get_material_pairings: PairingsResponse;
@@ -48,9 +44,6 @@ export type OperationResponses = {
     list_associated_finishes: DeclaredAssociationsResponse;
     list_associated_products: DeclaredAssociationsResponse;
     list_brands: ListBrandsPage;
-    list_catalog_documents: CatalogDocumentList;
-    list_catalog_pages: CatalogPageListResult;
-    list_catalog_product_references: CatalogProductReferenceReadResult;
     list_categories: CategoriesListResult;
     list_material_blocks: MaterialBlockProjection;
     list_material_documents: MaterialDocumentPage;

package/operations.generated.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.8.0";
-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 ["catalogReferencesForVariants", "POST", "/api/v1/catalogs/references", "get_catalog_references_batch"], 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"]];
+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 ["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"]];
 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

@@ -37,37 +37,6 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/catalog/generation",
         "get_catalog_generation",
     ],
-    ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
-    [
-        "catalogPages",
-        "GET",
-        "/api/v1/catalogs/{catalogId}/pages",
-        "list_catalog_pages",
-    ],
-    [
-        "catalogPageRepresentation",
-        "GET",
-        "/api/v1/catalog-pages/{pageId}/representation",
-        "get_catalog_page_representation",
-    ],
-    [
-        "catalogReferences",
-        "GET",
-        "/api/v1/catalogs/{catalogId}/references",
-        "list_catalog_product_references",
-    ],
-    [
-        "catalogReferencesForVariants",
-        "POST",
-        "/api/v1/catalogs/references",
-        "get_catalog_references_batch",
-    ],
-    [
-        "catalogDocumentAccess",
-        "GET",
-        "/api/v1/catalogs/documents/{documentId}",
-        "get_catalog_document_access",
-    ],
     [
         "materialBlocks",
         "GET",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "2.3.0",
+  "version": "3.0.1",
   "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 ["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", "get_catalog_references_batch", "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"];
+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_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"];
 export declare const RESPONSE_SCHEMA_CATALOG_JSON: string;