@instruments/materialgraph 0.21.0 → 0.23.0

package/client-vocabulary.d.ts

@@ -1,7 +1,7 @@
 import { HttpTransport } from "./http-transport.js";
-import type { ColourFacetsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SuggestColourResponse, SuggestOptions, SuggestResponse } from "./types.js";
+import type { ColourFacetsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourOptions, ResolveColourResponse, SuggestColourResponse, SuggestOptions, SuggestResponse } from "./types.js";
 export declare function colourFacets(transport: HttpTransport, signal?: AbortSignal): Promise<ColourFacetsResponse>;
-export declare function resolveColour(transport: HttpTransport, name: string, signal?: AbortSignal): Promise<ResolveColourResponse>;
+export declare function resolveColour(transport: HttpTransport, name: string, signal?: AbortSignal, options?: ResolveColourOptions): Promise<ResolveColourResponse>;
 export declare function suggestColour(transport: HttpTransport, q: string, options?: {
     limit?: number;
 }, signal?: AbortSignal): Promise<SuggestColourResponse>;

package/client-vocabulary.js

@@ -4,8 +4,8 @@ import { suggestQuery } from "./suggest-types.js";
 export function colourFacets(transport, signal) {
     return transport.requestJson(resolveOperation("get_colour_facets"), { signal });
 }
-export function resolveColour(transport, name, signal) {
-    return transport.requestJson(resolveOperation("resolve_colour_name"), { query: { name }, signal });
+export function resolveColour(transport, name, signal, options) {
+    return transport.requestJson(resolveOperation("resolve_colour_name"), { query: { name, corpusScope: options?.corpusScope }, signal });
 }
 export function suggestColour(transport, q, options, signal) {
     return transport.requestJson(resolveOperation("suggest_colour_names"), { query: { q, limit: options?.limit }, signal });

package/client.d.ts

@@ -30,7 +30,7 @@ import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-t
 import type { SlotPoolsRequest, SlotPoolsResponse } from "./slot-pool-types.js";
 import type { FindSubstitutesOptions, FindSubstitutesResponse } from "./substitute-types.js";
 import type { ProductTypeCoverageOptions, ProductTypeStatusCoverage } from "./taxonomy-coverage-types.js";
-import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
+import type { ApplicableSpecsResponse, BrandOptions, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourOptions, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, SuggestOptions, SuggestResponse, TaxonomyResponse, VocabularySearchOptions, WhoamiResponse } from "./types.js";
 /**
  * The MaterialGraph client — every lens on the graph, on one object.
  *
@@ -287,8 +287,8 @@ export declare class MaterialGraphClient extends CatalogueClient {
     }, signal?: AbortSignal): Promise<MaterialsBatchTileResponse>;
     /** Vocabulary families and counts; use `colours.profiles()` for a material palette. */
     colourFacets(signal?: AbortSignal): Promise<ColourFacetsResponse>;
-    /** Resolve a colour name to its canonical hex when recognised. */
-    resolveColour(name: string, signal?: AbortSignal): Promise<ResolveColourResponse>;
+    /** Resolve a colour name to its hex, and the named paint's catalogue variant. */
+    resolveColour(name: string, signal?: AbortSignal, options?: ResolveColourOptions): Promise<ResolveColourResponse>;
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
     suggestColour(q: string, options?: {
         limit?: number;

package/client.js

@@ -362,9 +362,9 @@ export class MaterialGraphClient extends CatalogueClient {
     colourFacets(signal) {
         return colourFacetsCall(this.#transport, signal);
     }
-    /** Resolve a colour name to its canonical hex when recognised. */
-    resolveColour(name, signal) {
-        return resolveColourCall(this.#transport, name, signal);
+    /** Resolve a colour name to its hex, and the named paint's catalogue variant. */
+    resolveColour(name, signal, options) {
+        return resolveColourCall(this.#transport, name, signal, options);
     }
     /** Ranked colour-name typeahead (GET `/api/v1/search/colours/suggest`). */
     suggestColour(q, options, signal) {

package/package.json

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

package/resolve-colour-types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Colour-name resolution (GET `/api/v1/search/colours/resolve`): the resolved
+ * colour, and whether the named paint is a variant in the catalogue.
+ */
+import type { CorpusScope } from "./corpus-scope-types.js";
+import type { VariantId } from "./identifiers.js";
+import type { OpenEnum } from "./types.js";
+/** Options for `resolveColour`. */
+export interface ResolveColourOptions {
+    /**
+     * Sets `inScope` on each catalogue variant the lookup reports. It never
+     * narrows the lookup. Absent leaves every `inScope` null.
+     */
+    corpusScope?: CorpusScope;
+}
+/** One catalogue variant carrying the named paint. */
+export interface ResolveColourCatalogueVariant {
+    variantId: VariantId;
+    /** The brand exactly as stored, suspect or not. */
+    brand: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    /** Whether the variant is in the requested scope; null when none was asked for. */
+    inScope: boolean | null;
+    /**
+     * True when the stored brand is Samplize, a sampling channel, and the listing
+     * is not Samplize's own: the colour is another maker's, so `brand` is not who
+     * made it. The variant is still the right one for the name.
+     */
+    parentageSuspect: boolean;
+}
+/**
+ * Whether the named paint is a variant in the catalogue. Exact, global, and
+ * never narrowed by `corpusScope`, and run only for a `brand` library hit.
+ * `not-in-catalogue` means the catalogue was searched and nothing carries the
+ * paint; `not-looked-up` means there was no one maker's paint to search for.
+ */
+export type ResolveColourVariant = ({
+    status: "matched";
+} & ResolveColourCatalogueVariant) | {
+    status: "ambiguous";
+    candidates: ResolveColourCatalogueVariant[];
+} | {
+    status: "not-in-catalogue";
+} | {
+    status: "not-looked-up";
+    reason: OpenEnum<"reference-colour" | "descriptive-colour" | "no-paint-identity" | "generic-colour" | "several-paints">;
+};
+export interface ResolveColourResponse {
+    match: {
+        hex: string;
+        name: string;
+        code?: string;
+        /** The ColorScope library the colour resolved in. Not necessarily a maker. */
+        libraryId?: string;
+        /**
+         * The library's own type: `brand` is a maker's paint, `reference` a colour
+         * standard (RAL, Pantone, HKS), `core` ColorScope's descriptive vocabulary.
+         * Present exactly when `libraryId` is. Only a `brand` hit is looked up.
+         */
+        libraryType?: OpenEnum<"brand" | "reference" | "core" | "consumer">;
+        /** The catalogue lookup for the name. Absent from servers that predate it. */
+        variant?: ResolveColourVariant;
+    } | null;
+}

package/resolve-colour-types.js

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

package/samplize-catalogue-types.d.ts

@@ -1,6 +1,11 @@
 export interface SamplizeCatalogueOptions {
     limit?: number;
+    /** Continue with unchanged filters and sourceVersion; omit when filters change. */
     after?: string;
+    /** Exact canonical identities, at most 100. Unknown/ineligible IDs are omitted; no substitution. Combined filters intersect. */
+    variantIds?: string[];
+    /** Exact source collection handle; publisher remains Samplize. */
+    collectionHandle?: string;
     /** Pin every subsequent page to the version returned by the first page. */
     sourceVersion?: string;
 }
@@ -49,6 +54,7 @@ export interface SamplizeCataloguePage {
     corpusScope: "samplizeCatalogue";
     sourceVersion: string;
     source: Record<string, unknown>;
+    /** Number of eligible records matching the supplied filters. */
     total: number;
     items: SamplizeCatalogueProduct[];
     nextCursor: string | null;

package/search-response-receipt-types.d.ts

@@ -37,7 +37,7 @@ export interface SearchEmptyOutcomeCounts {
  */
 export type SearchEmptyOutcome = {
     kind: "proven-corpus-empty";
-    basis: OpenEnum<"spec-allowlist" | "brand-scope">;
+    basis: OpenEnum<"spec-allowlist" | "brand-scope" | "brand-product-type">;
     exhaustive: true;
     sourceEmpty?: boolean | null;
     counts?: SearchEmptyOutcomeCounts;

package/types.d.ts

@@ -625,14 +625,6 @@ export interface MaterialsBatchDetailResponse {
     /** Requested ids that resolved to nothing. Echoed verbatim, opaque. */
     missingIds: VariantId[];
 }
-export interface ResolveColourResponse {
-    match: {
-        hex: string;
-        name: string;
-        code?: string;
-        libraryId?: string;
-    } | null;
-}
 export interface SuggestColourResponse {
     suggestions: Array<{
         term: string;
@@ -655,6 +647,7 @@ export interface ResolveAttributeResponse {
 }
 export type * from "./catalog-discovery-types.js";
 export type * from "./resolve-types.js";
+export type * from "./resolve-colour-types.js";
 export type * from "./suggest-types.js";
 export type * from "./by-spec-types.js";
 export interface WhoamiResponse {