@instruments/materialgraph 0.29.0 → 0.31.0

package/resolve-colour-types.d.ts

@@ -28,7 +28,7 @@ export type ResolveColourCatalogueVariant = {
     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
+     * is not Samplize's own: the colour is another brand's, so `brand` is not who
      * made it. The variant is still the right one for the name.
      */
     parentageSuspect: boolean;
@@ -37,7 +37,7 @@ export type ResolveColourCatalogueVariant = {
  * 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.
+ * paint; `not-looked-up` means there was no one brand's paint to search for.
  */
 export type ResolveColourVariant = ({
     status: "matched";
@@ -62,17 +62,17 @@ export type ResolveColourResponse = {
         libraryName: string;
         code?: string;
     }[];
-    /** Generic meaning; maker-specific paint identity is carried by match. */
+    /** Generic meaning; brand-specific paint identity is carried by match. */
     genericResolution: ColorResolution;
     match: {
         matchTarget: MatchTarget;
         hex: string;
         name: string;
         code?: string;
-        /** The ColorScope library the colour resolved in. Not necessarily a maker. */
+        /** The ColorScope library the colour resolved in. Not necessarily a brand. */
         libraryId?: string;
         /**
-         * The library's own type: `brand` is a maker's paint, `reference` a colour
+         * The library's own type: `brand` is a brand'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.
          */

package/resolve-variant-types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Public wire types for `POST /api/v1/variants/resolve` (MG-1672's
+ * `resolve_variant` contract).
+ *
+ * These intentionally mirror the domain-owned Zod contract
+ * (`@materialgraph/products/identify-contract`) rather than importing it: the
+ * published SDK must carry no workspace package dependency.
+ */
+/**
+ * What `mg.resolveVariant()` accepts. Give `url` alone, or `code` with
+ * `brandId` (from `mg.brands()`) when there is no page to read. `labels` are
+ * product names visible on the page, sent only to tell several URL candidates
+ * apart - they never widen a search or invent an identity on their own.
+ */
+export type ResolveVariantInput = {
+    url?: string;
+    code?: string;
+    brandId?: string;
+    labels?: string[];
+};
+/** One identified, placed or bounded-candidate subject. */
+export type ResolveVariantSubject = {
+    kind: "variant" | "brand";
+    id: string;
+    name: string;
+    code?: string;
+    brand?: {
+        id: string;
+        name: string;
+    };
+};
+/** What stood behind an outcome. Exact and scoreless: never a similarity guess. */
+export type ResolveVariantEvidence = {
+    kind: "brand-url" | "brand-homepage" | "brand-code" | "visible-label";
+    url?: string;
+    detail: string;
+};
+/** The submitted URL, normalised, and the steps that normalisation took. Absent for a code-only call. */
+export type ResolveVariantReceipt = {
+    submittedUrl: string;
+    normalizedUrl: string;
+    normalizationSteps: string[];
+};
+type ResolveVariantOutputBase = {
+    evidence: ResolveVariantEvidence[];
+    receipt?: ResolveVariantReceipt;
+};
+/**
+ * Why nothing was resolved. Absent and empty differ: this names what was
+ * looked for and not found, never a similarity guess.
+ */
+export type ResolveVariantUnresolvedReason = "no-stored-url" | "no-code-match";
+/**
+ * What `mg.resolveVariant()` returns: the `resolve_variant` tool's own output,
+ * unwrapped. Exact identities only - no rung carries a similarity score.
+ */
+export type ResolveVariantOutput = (ResolveVariantOutputBase & {
+    outcome: "identified";
+    subject: ResolveVariantSubject & {
+        kind: "variant";
+    };
+}) | (ResolveVariantOutputBase & {
+    outcome: "placed";
+    subject: ResolveVariantSubject & {
+        kind: "brand";
+    };
+}) | (ResolveVariantOutputBase & {
+    outcome: "ambiguous";
+    candidates: ResolveVariantSubject[];
+    truncated: boolean;
+}) | (ResolveVariantOutputBase & {
+    outcome: "unresolved";
+    reason: ResolveVariantUnresolvedReason;
+});
+export {};

package/{identify-types.js → resolve-variant-types.js}

@@ -1,6 +1,6 @@
 /**
- * Public wire types for `POST /api/v1/identify` (MG-1672's `resolve_variant`
- * contract).
+ * Public wire types for `POST /api/v1/variants/resolve` (MG-1672's
+ * `resolve_variant` contract).
  *
  * These intentionally mirror the domain-owned Zod contract
  * (`@materialgraph/products/identify-contract`) rather than importing it: the

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.7.0";
 /** Every SDK operation whose success response has a published JSON Schema. */
-export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["samplize_colorvec_cache", "samplize_catalogue_search", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "search_materials_post", "retrieval.identify", "match_material", "search_suggest", "get_colour_stats", "coordinate_materials", "plan_material_query", "samplize_catalogue_products", "search_materials_get", "search_by_colour", "get_material", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "get_composition_report", "list_schema_blocks", "list_schema_attributes", "list_schema_verticals", "list_schema_product_types", "list_schema_units", "list_schema_value_dictionaries", "list_schema_source_requirements", "list_schema_product_type_templates", "list_schema_mappings", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "get_category_colour_profiles", "resolve_colour_name", "suggest_colour_names", "catalog_list_attributes", "list_categories", "get_category", "get_product_type_status_coverage", "whoami", "get_material_demand", "search_by_palette", "extract_image_palette", "search_by_gradient", "list_spec_facets", "list_brands", "upload_source_material", "get_source_material_batch", "list_source_material_comments", "post_source_material_comment", "create_public_run", "get_public_run", "get_verdict_citation", "get_demand_batch", "resolveCodeAdvisory", "list_code_context", "list_code_requirements"];
+export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["samplize_colorvec_cache", "samplize_catalogue_search", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "search_materials_post", "match_material", "plan_material_query", "samplize_catalogue_products", "search_materials_get", "search_by_colour", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_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", "find_variants_by_colour", "find_variants_by_vector", "find_companions", "resolve_variant", "get_variant", "resolve_colour_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "search_by_palette", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run", "get_verdict_citation"];
 export declare const RESPONSE_SCHEMA_CATALOGUE_JSON: string;