@instruments/materialgraph 0.35.0 → 0.36.0

package/client.d.ts

@@ -6,7 +6,7 @@ import type { ResolvedVerdictCitation } from "./citation-types.js";
 import type { MaterialGraphClientOptions } from "./client-config.js";
 import { ColorsClient } from "./colors-client.js";
 import type { RateLimit } from "./errors.js";
-import type { FindCompanionsInput, FindCompanionsOutput } from "./find-companions-types.js";
+import type { FindSampledTogetherInput, FindSampledTogetherOutput } from "./find-sampled-together-types.js";
 import type { FindVariantsByColorInput, FindVariantsByColorOutput } from "./find-variants-by-color-types.js";
 import type { FindVariantsByVectorInput, FindVariantsByVectorOutput } from "./find-variants-by-vector-types.js";
 import type { GetVariantOptions, GetVariantOutput } from "./get-variant-types.js";
@@ -200,15 +200,15 @@ export declare class MaterialGraphClient extends CatalogueClient {
     findVariantsByColor(input: FindVariantsByColorInput, signal?: AbortSignal): Promise<FindVariantsByColorOutput>;
     /**
      * THE QUESTION: "what did designers sample together with these?" (POST
-     * `/api/v1/variants/companions`, MG-2332). Give `variantIds` and/or
+     * `/api/v1/variants/sampled-together`, MG-2332). Give `variantIds` and/or
      * `materials` (free-text names, one variant each, at most twelve together);
-     * companions come back strongest first, each with its `lift`,
-     * `seedMatchCount`, `relation` and a one-line `reason`. `projectType` reads one
+     * the materials come back other brands first, then the most projects, each
+     * with its `lift`, `seedMatchCount`, `relation` and a one-line `reason`. `projectType` reads one
      * sector; `include` adds `image` and `color` fields a lean page leaves out.
      * A sample order shows sampling, never specification. Read `unresolved`
      * before presenting: a scheme of four that resolved two is a different claim.
      */
-    findCompanions(input: FindCompanionsInput, signal?: AbortSignal): Promise<FindCompanionsOutput>;
+    findSampledTogether(input: FindSampledTogetherInput, signal?: AbortSignal): Promise<FindSampledTogetherOutput>;
     /**
      * THE QUESTION: "what looks or feels like this?" (POST
      * `/api/v1/variants/by-vector`, MG-2231). Eligible variants ranked by

package/client.js

@@ -282,16 +282,16 @@ export class MaterialGraphClient extends CatalogueClient {
     }
     /**
      * THE QUESTION: "what did designers sample together with these?" (POST
-     * `/api/v1/variants/companions`, MG-2332). Give `variantIds` and/or
+     * `/api/v1/variants/sampled-together`, MG-2332). Give `variantIds` and/or
      * `materials` (free-text names, one variant each, at most twelve together);
-     * companions come back strongest first, each with its `lift`,
-     * `seedMatchCount`, `relation` and a one-line `reason`. `projectType` reads one
+     * the materials come back other brands first, then the most projects, each
+     * with its `lift`, `seedMatchCount`, `relation` and a one-line `reason`. `projectType` reads one
      * sector; `include` adds `image` and `color` fields a lean page leaves out.
      * A sample order shows sampling, never specification. Read `unresolved`
      * before presenting: a scheme of four that resolved two is a different claim.
      */
-    async findCompanions(input, signal) {
-        return await this.#post("find_companions", input, signal);
+    async findSampledTogether(input, signal) {
+        return await this.#post("find_sampled_together", input, signal);
     }
     /**
      * THE QUESTION: "what looks or feels like this?" (POST

package/{find-companions-types.d.ts → find-sampled-together-types.d.ts}

@@ -1,32 +1,32 @@
 /**
- * @module find-companions-types
- * @description Hand-maintained mirror of `find_companions`' (MG-2332) input and
+ * @module find-sampled-together-types
+ * @description Hand-maintained mirror of `find_sampled_together`'s (MG-2332) input and
  * output wire shapes. The source of truth is
- * `packages/products/src/cospec/schema.ts` (`findCompanionsInputSchema`,
- * `findCompanionsResultSchema`). This SDK has no RUNTIME dependency on
+ * `packages/products/src/cospec/schema.ts` (`findSampledTogetherInputSchema`,
+ * `findSampledTogetherResultSchema`). This SDK has no RUNTIME dependency on
  * `@materialgraph/products` (it's a devDependency only, for the parity tests in
  * `__tests__/`), so the shapes are copied here rather than imported.
  * `contract-parity.test.ts` keeps this mirror honest against the server types,
  * the project-type list included.
  */
 /** The closed sector vocabulary co-specification evidence is tagged with. */
-export type CompanionProjectType = "Workplace" | "Residential" | "Institution Education" | "Hospitality: Hotel" | "Mixed-Use & Multi-Unit Residential" | "Healthcare" | "Hospitality: Restaurant" | "Government" | "Senior Living" | "Retail" | "Other" | "Sports Entertainment" | "Wellness" | "Medical Dental" | "Aviation" | "Industrial" | "Tech" | "Transportation" | "Single Family" | "Condominium Cooperative" | "Marine" | "Power & Energy" | "University Design Program: Interior Design" | "Non-Billable" | "University Design Program: Interior Architecture" | "University Design Program: Architecture" | "Historic Preservation";
+export type SampledTogetherProjectType = "Workplace" | "Residential" | "Institution Education" | "Hospitality: Hotel" | "Mixed-Use & Multi-Unit Residential" | "Healthcare" | "Hospitality: Restaurant" | "Government" | "Senior Living" | "Retail" | "Other" | "Sports Entertainment" | "Wellness" | "Medical Dental" | "Aviation" | "Industrial" | "Tech" | "Transportation" | "Single Family" | "Condominium Cooperative" | "Marine" | "Power & Energy" | "University Design Program: Interior Design" | "Non-Billable" | "University Design Program: Interior Architecture" | "University Design Program: Architecture" | "Historic Preservation";
 /** At least one of `variantIds` and `materials`, at most twelve together. */
-export type FindCompanionsInput = {
+export type FindSampledTogetherInput = {
     /** Optional row fields: image adds imageUrl, color adds swatches. */
     include?: ("image" | "color")[];
     /** Ops and audit switch: leave sample cards in. Default false. */
     includeSamplingArtifacts?: boolean;
-    /** Companions to return, default 20, at most 100. */
+    /** Materials to return, default 20, at most 100. */
     limit?: number;
     /** Names to resolve when you hold no ids. Misses come back unresolved. */
     materials?: string[];
-    /** Only companions sampled together in projects of this sector. */
-    projectType?: CompanionProjectType;
-    /** Variants to find companions for. */
+    /** Only materials sampled together in projects of this sector. */
+    projectType?: SampledTogetherProjectType;
+    /** Variants to find sampled-together materials for. */
     variantIds?: string[];
 };
-export type FindCompanionsRow = {
+export type FindSampledTogetherRow = {
     brand: string;
     /** Palette likeness to the seeds. Present with `include: ["color"]`; never reorders. */
     colorFit?: number | null;
@@ -37,8 +37,8 @@ export type FindCompanionsRow = {
     product: string;
     /** Why it was suggested, in one line. */
     reason: string;
-    /** `companion` is another brand; `brand_sibling` and `colorway` share the seed's. */
-    relation: "companion" | "brand_sibling" | "colorway";
+    /** `other_brand` is another brand; `brand_sibling` and `colorway` share the seed's. */
+    relation: "other_brand" | "brand_sibling" | "colorway";
     /** How many seeds it was sampled with. */
     seedMatchCount: number;
     /** Present with `include: ["color"]`. */
@@ -49,9 +49,9 @@ export type FindCompanionsRow = {
     variantId: string;
     variantName: string | null;
 };
-export type FindCompanionsOutput = {
-    /** Strongest first: seeds matched, then summed lift, one row per product. */
-    companions: FindCompanionsRow[];
+export type FindSampledTogetherOutput = {
+    /** Other brands first, then seeds matched, then lift weighted by projects; one row per product. */
+    sampledTogether: FindSampledTogetherRow[];
     /** The seeds as resolved, so a caller sees what a name became. */
     seeds: {
         brand: string;

package/{find-companions-types.js → find-sampled-together-types.js}

@@ -1,9 +1,9 @@
 /**
- * @module find-companions-types
- * @description Hand-maintained mirror of `find_companions`' (MG-2332) input and
+ * @module find-sampled-together-types
+ * @description Hand-maintained mirror of `find_sampled_together`'s (MG-2332) input and
  * output wire shapes. The source of truth is
- * `packages/products/src/cospec/schema.ts` (`findCompanionsInputSchema`,
- * `findCompanionsResultSchema`). This SDK has no RUNTIME dependency on
+ * `packages/products/src/cospec/schema.ts` (`findSampledTogetherInputSchema`,
+ * `findSampledTogetherResultSchema`). This SDK has no RUNTIME dependency on
  * `@materialgraph/products` (it's a devDependency only, for the parity tests in
  * `__tests__/`), so the shapes are copied here rather than imported.
  * `contract-parity.test.ts` keeps this mirror honest against the server types,

package/index.d.ts

@@ -6,7 +6,7 @@ export type * from "./search-variants-types.js";
 export type * from "./list-enum-values-types.js";
 export type * from "./get-variant-types.js";
 export type * from "./image-reference-types.js";
-export type * from "./find-companions-types.js";
+export type * from "./find-sampled-together-types.js";
 export type * from "./find-variants-by-color-types.js";
 export { FIND_VARIANTS_BY_VECTOR_MODES } from "./find-variants-by-vector-types.js";
 export type * from "./find-variants-by-vector-types.js";

package/operations.d.ts

@@ -1,5 +1,5 @@
 export declare const MATERIALGRAPH_API_VERSION = "0.8.0";
-declare const OPERATION_DEFINITIONS: readonly [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 ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], readonly ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_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", "POST", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findCompanions", "POST", "/api/v1/variants/companions", "find_companions"], 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 ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], readonly ["workflows.streamRunEvents", "GET", "/api/v1/workflows/{workflowId}/runs/{runId}/events", "list_public_run_events"]];
+declare const OPERATION_DEFINITIONS: readonly [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 ["samplizeCatalogue", "GET", "/api/v1/catalogues/samplize/products", "samplize_catalogue_products"], readonly ["catalogueReferences", "POST", "/api/v1/catalogues/references", "get_catalogue_references_batch"], readonly ["catalogueCollections", "GET", "/api/v1/catalogues/collections", "list_catalogue_channel_collections"], readonly ["catalogueDocumentAccess", "GET", "/api/v1/catalogues/documents/{documentId}", "get_catalogue_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", "POST", "/api/v1/variants/by-color", "find_variants_by_color"], readonly ["findVariantsByVector", "POST", "/api/v1/variants/by-vector", "find_variants_by_vector"], readonly ["findSampledTogether", "POST", "/api/v1/variants/sampled-together", "find_sampled_together"], 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 ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"], 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 = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];

package/operations.js

@@ -107,7 +107,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/variants/by-vector",
         "find_variants_by_vector",
     ],
-    ["findCompanions", "POST", "/api/v1/variants/companions", "find_companions"],
+    [
+        "findSampledTogether",
+        "POST",
+        "/api/v1/variants/sampled-together",
+        "find_sampled_together",
+    ],
     ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"],
     ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"],
     [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.35.0",
+  "version": "0.36.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 ["list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "samplize_catalogue_products", "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", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_companions", "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", "get_verdict_citation"];
+export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "samplize_catalogue_products", "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", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_sampled_together", "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", "get_verdict_citation"];
 export declare const RESPONSE_SCHEMA_CATALOGUE_JSON: string;