@instruments/materialgraph 1.0.1 → 1.2.0

package/client.d.ts

@@ -11,6 +11,7 @@ import type { FindVariantsByVectorInput, FindVariantsByVectorOutput } from "./fi
 import type { GetVariantOptions, GetVariantOutput } from "./get-variant-types.js";
 import type { VariantId } from "./identifiers.js";
 import type { ListEnumValuesOptions, ListEnumValuesResult } from "./list-enum-values-types.js";
+import type { ListSampledTogetherPairsInput, ListSampledTogetherPairsOutput } from "./list-sampled-together-pairs-types.js";
 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";
@@ -214,6 +215,14 @@ export declare class MaterialGraphClient extends CatalogClient {
      * before presenting: a scheme of four that resolved two is a different claim.
      */
     findSampledTogether(input: FindSampledTogetherInput, signal?: AbortSignal): Promise<FindSampledTogetherOutput>;
+    /**
+     * Every Sampled Together pair in the current generation (GET
+     * `/api/v1/variants/sampled-together/pairs`), trailing 36 months, sampled,
+     * each pair once with `a < b`. `aProjects` and `bProjects` are each side's
+     * own project total, so a sample pack can be dropped without one call per
+     * variant. Follow `nextCursor` until it is null; a page is not a total.
+     */
+    listSampledTogetherPairs(input?: ListSampledTogetherPairsInput, signal?: AbortSignal): Promise<ListSampledTogetherPairsOutput>;
     /**
      * THE QUESTION: "what looks or feels like this?" (POST
      * `/api/v1/variants/by-vector`, MG-2231). Eligible variants ranked by

package/client.js

@@ -326,6 +326,22 @@ export class MaterialGraphClient extends CatalogClient {
     async findSampledTogether(input, signal) {
         return await this.#get("find_sampled_together", { ...input }, signal);
     }
+    /**
+     * Every Sampled Together pair in the current generation (GET
+     * `/api/v1/variants/sampled-together/pairs`), trailing 36 months, sampled,
+     * each pair once with `a < b`. `aProjects` and `bProjects` are each side's
+     * own project total, so a sample pack can be dropped without one call per
+     * variant. Follow `nextCursor` until it is null; a page is not a total.
+     */
+    async listSampledTogetherPairs(input = {}, signal) {
+        return await this.#get("list_sampled_together_pairs", {
+            ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+            ...(input.limit === undefined ? {} : { limit: String(input.limit) }),
+            ...(input.minProjects === undefined
+                ? {}
+                : { minProjects: String(input.minProjects) }),
+        }, signal);
+    }
     /**
      * THE QUESTION: "what looks or feels like this?" (POST
      * `/api/v1/variants/by-vector`, MG-2231). Eligible variants ranked by

package/errors.d.ts

@@ -88,8 +88,7 @@ type TransportErrorInput = {
  * field was added to remove. All ten members below were unreachable.
  *
  * So: the server's own contract is retained, and nothing else is. Adding a
- * member to a problem response means adding it here too, and
- * `problem-extension-parity.test.ts` fails when the two disagree.
+ * member to a problem response means adding it here too.
  */
 export declare const MATERIALGRAPH_PROBLEM_EXTENSIONS: readonly ["ambiguous_brands", "brand_candidates", "content_length", "did_you_mean", "empty_brands", "limit_bytes", "missing_env", "orderable_attributes", "populated_alternatives", "refused_criteria", "unknown_attributes", "unknown_brands", "unknown_fields", "unknown_parameters", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
 /** The one error class thrown by all SDK transport and HTTP failures. */

package/errors.js

@@ -19,8 +19,7 @@ const RETRIABLE_STATUS = new Set([502, 503, 504]);
  * field was added to remove. All ten members below were unreachable.
  *
  * So: the server's own contract is retained, and nothing else is. Adding a
- * member to a problem response means adding it here too, and
- * `problem-extension-parity.test.ts` fails when the two disagree.
+ * member to a problem response means adding it here too.
  */
 export const MATERIALGRAPH_PROBLEM_EXTENSIONS = [
     "ambiguous_brands",

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

@@ -51,7 +51,7 @@ export type FindSampledTogetherRow = {
     variantName: string | null;
 };
 export type FindSampledTogetherOutput = {
-    /** Other brands first, then seeds matched, then lift weighted by projects; one row per product. */
+    /** Other brands first; within each, product type groups in turn, each group best first (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: {

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

@@ -67,10 +67,12 @@ export type PaintCatalogVariant = {
     variantName: string | null;
 };
 export type ResolvedColor = {
+    /** Other meanings of the same words, offered: ColorScope's color when a paint's exact name led. */
+    alternatives?: ColorAlternative[];
     catalogVariant: PaintCatalogVariant | null;
     hex: string;
     index: number;
-    /** `region`: a named meaning's own OKLCh bounds, kept — never collapsed to one hex. */
+    /** `region`: a color family's own OKLCh bounds. `point`: a paint, hex or named color, held within ColorScope's Related band and ordered by Closeness. */
     kind: "point" | "region";
     /** Image-extracted or stored target-variant swatch share; else null. */
     share: number | null;

package/get-variant-types.d.ts

@@ -46,6 +46,7 @@ export type GetVariantIfc = {
  * false or zero.
  */
 export type GetVariantOutput = {
+    /** Whether this variant may appear in its Brand's catalog. Material-only lists also require Search Catalog membership. Reads by id include ineligible variants. */
     eligible: boolean;
     channels: string[];
     palette: {
@@ -93,6 +94,8 @@ 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. */
+    variantLabel: string | null;
     /** Requested blocks or attributes the variant's product type does not carry. */
     notApplicable?: ListVariantsNotApplicable;
     /** Present when `ifc` was asked for. */

package/index.d.ts

@@ -7,6 +7,7 @@ export type { ListEnumValuesOptions, EnumValueMatch, EnumValueItem, ListEnumValu
 export type { GetVariantIfc, GetVariantOptions, GetVariantOutput, } from "./get-variant-types.js";
 export type { ImageReferenceInput } from "./image-reference-types.js";
 export type { SampledTogetherProjectType, FindSampledTogetherInput, FindSampledTogetherRow, FindSampledTogetherOutput, } from "./find-sampled-together-types.js";
+export type { ListSampledTogetherPairsInput, ListSampledTogetherPairsOutput, SampledTogetherPair, } from "./list-sampled-together-pairs-types.js";
 export type { FindVariantsByColorMode, ColorConditionInput, FindVariantsByColorInput, ColorConditionReceipt, PaintCatalogVariant, ResolvedColor, ColorAlternative, UnresolvedColor, ColorVariantMatch, ColorPageInfo, FindVariantsByColorContainsResult, FindVariantsByColorPaletteResult, ColorRankedSeed, ColorRankMatch, ResolvedColorReference, CompareColorSimilarityReference, FindVariantsByColorRerankResult, FindVariantsByColorOutput, } from "./find-variants-by-color-types.js";
 export { FIND_VARIANTS_BY_VECTOR_MODES } from "./find-variants-by-vector-types.js";
 export type { FindVariantsByVectorMode, FindVariantsByVectorQuery, FindVariantsByVectorInput, FindVariantsByVectorItem, FindVariantsByVectorReference, FindVariantsByVectorScan, FindVariantsByVectorTimings, FindVariantsByVectorOutput, } from "./find-variants-by-vector-types.js";

package/list-sampled-together-pairs-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module list-sampled-together-pairs-types
+ * @description Hand-maintained mirror of `list_sampled_together_pairs`' wire
+ * shapes. The source of truth is
+ * `packages/sampling/src/sampled-together-pairs.ts`; this SDK has no runtime
+ * dependency on `@materialgraph/sampling`, so the shapes are copied here.
+ */
+export type ListSampledTogetherPairsInput = {
+    /** `nextCursor` from the previous page. */
+    cursor?: string;
+    /** Pairs per page, at most 5,000. Default 2,000. */
+    limit?: number;
+    /** Smallest project count a pair needs. Default 3. */
+    minProjects?: number;
+};
+export type SampledTogetherPair = {
+    a: string;
+    b: string;
+    /** Projects that sampled both. */
+    projects: number;
+    customers: number;
+    /** Above 1 is sampled together more often than chance. */
+    lift: number;
+    lastSampledTogetherAt: string | null;
+    /** Each side's own sampled project total; null when unknown. */
+    aProjects: number | null;
+    bProjects: number | null;
+};
+export type ListSampledTogetherPairsOutput = {
+    window: "trailing_36mo";
+    signal: "sampled";
+    windowStart: string | null;
+    /** How fresh the pair evidence is. */
+    windowEnd: string | null;
+    /** End of the window the per-side totals were counted over. */
+    projectTotalsWindowEnd: string | null;
+    pairs: SampledTogetherPair[];
+    nextCursor: string | null;
+};

package/list-sampled-together-pairs-types.js

@@ -0,0 +1,8 @@
+/**
+ * @module list-sampled-together-pairs-types
+ * @description Hand-maintained mirror of `list_sampled_together_pairs`' wire
+ * shapes. The source of truth is
+ * `packages/sampling/src/sampled-together-pairs.ts`; this SDK has no runtime
+ * dependency on `@materialgraph/sampling`, so the shapes are copied here.
+ */
+export {};

package/list-variants-types.d.ts

@@ -207,6 +207,8 @@ 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. */
+    variantLabel: string | null;
     notApplicable?: ListVariantsNotApplicable;
     preference?: ListVariantsPreference;
     product: {

package/operation-responses.d.ts

@@ -9,6 +9,7 @@ import type { FindVariantsByColorOutput } from "./find-variants-by-color-types.j
 import type { FindVariantsByVectorOutput } from "./find-variants-by-vector-types.js";
 import type { GetVariantOutput } from "./get-variant-types.js";
 import type { ListEnumValuesResult } from "./list-enum-values-types.js";
+import type { ListSampledTogetherPairsOutput } from "./list-sampled-together-pairs-types.js";
 import type { ListVariantFacetsOutput } from "./list-variant-facets-types.js";
 import type { ListVariantsOutput } from "./list-variants-types.js";
 import type { MaterialDocumentPage, VariantAssetPage } from "./material-asset-types.js";
@@ -30,6 +31,7 @@ export type OperationResponses = {
     create_public_run: CreatePublicRunResponse;
     extract_image_palette: ExtractPaletteResponse;
     find_sampled_together: FindSampledTogetherOutput;
+    list_sampled_together_pairs: ListSampledTogetherPairsOutput;
     find_variants_by_color: FindVariantsByColorOutput;
     find_variants_by_vector: FindVariantsByVectorOutput;
     get_applicability: ApplicabilityResponse;

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 ["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 ["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

@@ -125,6 +125,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/variants/sampled-together",
         "find_sampled_together",
     ],
+    [
+        "listSampledTogetherPairs",
+        "GET",
+        "/api/v1/variants/sampled-together/pairs",
+        "list_sampled_together_pairs",
+    ],
     ["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": "1.0.1",
+  "version": "1.2.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", "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 ["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;