@instruments/materialgraph 0.18.0 → 0.20.0

package/operations.js

@@ -1,6 +1,42 @@
 import { MaterialGraphError } from "./errors.js";
 export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
+    [
+        "colours.complete",
+        "POST",
+        "/api/v1/colours/palettes/complete",
+        "complete_interior_palette",
+    ],
+    [
+        "colours.discover",
+        "GET",
+        "/api/v1/colours/palettes",
+        "discover_interior_palettes",
+    ],
+    [
+        "samplizeColorVecCache",
+        "GET",
+        "/api/v1/catalogues/samplize/colorvec",
+        "samplize_colorvec_cache",
+    ],
+    [
+        "samplizeCatalogueSearch",
+        "POST",
+        "/api/v1/catalogues/samplize/search",
+        "samplize_catalogue_search",
+    ],
+    [
+        "scheduleReferences.list",
+        "GET",
+        "/api/v1/schedules/{scheduleId}/references",
+        "list_schedule_reference_feedback",
+    ],
+    [
+        "scheduleReferences.put",
+        "PUT",
+        "/api/v1/schedules/{scheduleId}/references/{referenceId}",
+        "put_schedule_reference_feedback",
+    ],
     ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
     [
         "catalogPages",
@@ -21,7 +57,14 @@ const OPERATION_DEFINITIONS = [
         "list_catalog_product_references",
     ],
     ["search", "POST", "/api/v1/search", "search_materials_post"],
+    ["identify", "POST", "/api/v1/identify", "retrieval.identify"],
     ["planQuery", "POST", "/api/v1/search/plan", "plan_material_query"],
+    [
+        "samplizeCatalogue",
+        "GET",
+        "/api/v1/catalogues/samplize/products",
+        "samplize_catalogue_products",
+    ],
     ["searchGet", "GET", "/api/v1/search", "search_materials_get"],
     ["match", "POST", "/api/v1/search/match", "match_material"],
     ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"],
@@ -62,6 +105,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/materials/{variantId}/assets",
         "list_material_assets",
     ],
+    [
+        "materialRenderAssets",
+        "GET",
+        "/api/v1/materials/{variantId}/render-assets",
+        "get_material_render_assets",
+    ],
     [
         "materialDocuments",
         "GET",
@@ -115,6 +164,12 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/materials/{variantId}/pairings",
         "get_material_pairings",
     ],
+    [
+        "findSubstitutes",
+        "POST",
+        "/api/v1/materials/{variantId}/substitutes",
+        "find_material_substitutes",
+    ],
     [
         "associatedFinishes",
         "GET",
@@ -178,6 +233,12 @@ const OPERATION_DEFINITIONS = [
     ["resolve", "POST", "/api/v1/resolve", "resolve_phrases"],
     ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"],
     ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"],
+    [
+        "productTypeCoverage",
+        "GET",
+        "/api/v1/taxonomy/coverage",
+        "get_product_type_status_coverage",
+    ],
     ["whoami", "GET", "/api/v1/whoami", "whoami"],
     ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"],
     ["demand", "GET", "/api/v1/demand", "get_material_demand"],
@@ -234,13 +295,13 @@ const OPERATION_DEFINITIONS = [
         "get_source_material_batch",
     ],
     [
-        "sourceMaterialComments",
+        "sourceMaterialComments.list",
         "GET",
         "/api/v1/source-material/{batchId}/sources/{sourceId}/comments",
         "list_source_material_comments",
     ],
     [
-        "sourceMaterialComments",
+        "sourceMaterialComments.post",
         "POST",
         "/api/v1/source-material/{batchId}/sources/{sourceId}/comments",
         "post_source_material_comment",
@@ -255,6 +316,7 @@ const OPERATION_DEFINITIONS = [
         "/api/v1/runs/{runId}/schedule",
         "get_run_finish_schedule",
     ],
+    ["citation", "GET", "/api/v1/citations/{citationId}", "get_verdict_citation"],
     [
         "streamRunEvents",
         "GET",

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
+    },
+    "./samplize-colorvec": {
+      "types": "./samplize-colorvec.d.ts",
+      "import": "./samplize-colorvec.js"
     }
   },
+  "dependencies": {
+    "@instruments/colorscope": "7.6.0"
+  },
   "license": "Proprietary",
   "engines": {
     "node": ">=24.0.0"

package/palette-completion-types.d.ts

@@ -0,0 +1,115 @@
+/** Public wire types; the SDK does not load the producer corpus. */
+export type CompositionalRole = "Foundation" | "Supporting" | "Accent";
+export interface RetainedColor {
+    readonly id: string;
+    readonly hex: string;
+    readonly role?: CompositionalRole;
+    readonly paintVariantId?: string;
+}
+export interface CompletionRequest {
+    readonly inputs: readonly RetainedColor[];
+    readonly maxDistance?: number;
+    readonly limit?: number;
+    readonly white?: "published" | "perceptual";
+    readonly memberCount?: number;
+    readonly excludeHexes?: readonly string[];
+}
+export interface CompletionAssignment {
+    readonly input: RetainedColor;
+    readonly referenceIndex: number;
+    readonly referenceHex: string;
+    readonly distance: number;
+}
+export interface CompletionMember {
+    readonly hex: string;
+    readonly referenceHex: string;
+    readonly referenceIndex: number;
+    readonly inputIds: readonly string[];
+    readonly role: CompositionalRole;
+    readonly proportion: number;
+    readonly sourceRole: string | null;
+    readonly sourceRelation: string | null;
+}
+export interface PaletteCompletion {
+    readonly uses?: readonly {
+        readonly inputId: string;
+        readonly role: CompositionalRole;
+        readonly proportions: readonly number[];
+    }[];
+    readonly id: string;
+    readonly reference: {
+        readonly anchorIndex?: number | null;
+        readonly libraryId: string;
+        readonly paletteId: string;
+        readonly name: string | null;
+        readonly maker: string | null;
+        readonly intent: "joint" | "alternatives";
+        readonly provenance: "authored" | "derived" | "generated";
+    };
+    readonly assignments: readonly CompletionAssignment[];
+    readonly members: readonly CompletionMember[];
+    readonly evidenceBasis: "published-composition" | "published-pair" | "nearby-adaptation";
+    readonly proportionBasis: "sourced" | "proposed";
+    readonly worstDistance: number;
+    readonly totalDistance: number;
+}
+export type PaletteCompleteInput = CompletionRequest & {
+    sourceVersion: string;
+};
+export interface PaletteDiscoverInput {
+    sourceVersion: string;
+    character?: "warm" | "cool" | "very-light" | "light" | "dark" | "muted" | "soft" | "vivid";
+    moreLike?: string;
+    cursor?: string;
+    limit?: number;
+}
+export interface MaterializedPalette {
+    completion: PaletteCompletion;
+    samples: Array<{
+        retainedPaint?: {
+            variantId: string;
+            name: string;
+            maker: string;
+        };
+        referenceIndex: number;
+        inputIds: readonly string[];
+        hex: string;
+        product: {
+            variantId: string;
+            productId: string;
+            hex: string;
+            name: string;
+            brand: {
+                slug: string;
+                name: string;
+            };
+        } | null;
+        status: string;
+        distance: number | null;
+        units: "oklab-euclidean";
+    }>;
+}
+interface PaletteVersions {
+    sourceVersion: string;
+    corpusVersion: string;
+    algorithmVersion: string;
+    transport: "colorscope-package";
+}
+export interface PaletteCompleteResponse extends PaletteVersions {
+    results: MaterializedPalette[];
+    coverage: {
+        status: string;
+        supported: number;
+    };
+    tolerance: {
+        bound: number;
+        units: string;
+        policy: string;
+    };
+}
+export interface PaletteDiscoverResponse extends PaletteVersions {
+    results: MaterializedPalette[];
+    total: number;
+    nextCursor: string | null;
+}
+export {};

package/palette-completion-types.js

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

package/palette-search-types.d.ts

@@ -1,3 +1,4 @@
+import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 /**
  * Wire types for MULTI-COLOUR search — `POST /api/v1/search/palettes` and
  * `POST /api/v1/search/gradients`.
@@ -34,6 +35,7 @@ export interface GradientStop {
     oklab?: OklabTriple;
 }
 export interface SearchPaletteInput {
+    corpusScope?: CorpusScope;
     /** The palette to match, 1–8 colours. */
     colours: PaletteQueryColour[];
     /**
@@ -46,14 +48,15 @@ export interface SearchPaletteInput {
     limit?: number;
 }
 export interface SearchGradientInput {
+    corpusScope?: CorpusScope;
     /** The ordered colour transition, 2–6 stops. */
     stops: GradientStop[];
     /** Results to return; defaults to 24, capped at 48. */
     limit?: number;
 }
 /**
- * One swatch of a candidate's colorscope-EXTRACTED palette. Derived from product
- * imagery, never a manufacturer's declared colour. `name` is null when no human
+ * One swatch used for scoring. Samplize paint uses its selected published hex;
+ * other materials use colorscope palettes extracted from imagery. `name` is null when no human
  * name was resolved — unnamed, not colourless.
  */
 export interface CandidateSwatch {
@@ -140,14 +143,24 @@ export interface HueGateReceipt {
  * materials match this palette" is not a claim you can make from it.
  */
 export interface SearchPaletteResponse {
+    corpusScope?: CorpusScopeReceipt;
     /** The query as interpreted — check it before trusting a surprising order. */
     query: {
+        /** Colours that actually ran after minor stated shares were omitted. */
         colours: Array<{
             hex: string;
             proportion?: number;
             weight?: number;
         }>;
+        /** Colours not searched because their stated share was below 5%. */
+        droppedColours: Array<{
+            hex: string;
+            proportion?: number;
+            weight?: number;
+        }>;
         logic: PaletteLogic;
+        /** `no_effective_colours` means no material query ran. */
+        outcome: OpenEnum<"matches" | "no_effective_colours">;
     };
     /** The hue-family admission gate this page was scored under. */
     hueGate: HueGateReceipt;
@@ -157,6 +170,7 @@ export interface SearchPaletteResponse {
 }
 /** A PAGE, NOT A CORPUS — see {@link SearchPaletteResponse}. */
 export interface SearchGradientResponse {
+    corpusScope?: CorpusScopeReceipt;
     query: {
         stops: string[];
         /** The sampled path points the search actually ran against. */

package/render-assets-types.d.ts

@@ -0,0 +1,65 @@
+import type { VariantId } from "./identifiers.js";
+export type RenderAssetChannelRole = "base-color" | "normal" | "roughness" | "metalness" | "height" | "ambient-occlusion";
+export type RenderAssetSourceBasis = "catalog_feed" | "declared" | "derived";
+export type RenderAssetUnavailableReason = "no_accepted_appearance" | "pending" | "withheld" | "rejected" | "superseded" | "variant_inactive" | "delivery_unverified" | "integrity_error";
+export interface RenderAssetFreshness {
+    revision: string;
+    updatedAt: string | null;
+    checkedAt: string | null;
+}
+export interface RenderAssetChannel {
+    role: RenderAssetChannelRole;
+    url: string;
+    sha256: string;
+    byteSize: number;
+    mimeType: "image/png";
+    width: number;
+    height: number;
+    bitDepth: 8 | 16;
+    colorSpace: "srgb" | "linear";
+}
+export interface MaterialRenderAssetsAvailable {
+    schemaVersion: "pbr-render-assets/v1";
+    variantId: VariantId;
+    status: "available";
+    setId: string;
+    state: "accepted";
+    sourceBasis: "derived";
+    fidelity: "unassessed";
+    acceptance: {
+        id: string;
+        verificationDecisionId: string;
+        acceptedAt: string;
+        checkVersion: string;
+        qa: {
+            status: "passed";
+            checkCount: number;
+        };
+        checkCount: number;
+    };
+    physicalRepeat: {
+        uMm: number;
+        vMm: number;
+        basis: "declared" | "measured";
+    };
+    tiling: {
+        u: boolean;
+        v: boolean;
+    };
+    normalConvention: "opengl" | "directx";
+    heightAmplitudeMm?: number;
+    channels: RenderAssetChannel[];
+    supersedesSetIds: string[];
+    freshness: RenderAssetFreshness;
+}
+export interface MaterialRenderAssetsUnavailable {
+    schemaVersion: "pbr-render-assets/v1";
+    variantId: VariantId;
+    status: "unavailable";
+    setId: string | null;
+    state: "pending" | "withheld" | "rejected" | "superseded" | "accepted" | null;
+    sourceBasis: RenderAssetSourceBasis | null;
+    reasonCodes: RenderAssetUnavailableReason[];
+    freshness: RenderAssetFreshness;
+}
+export type MaterialRenderAssets = MaterialRenderAssetsAvailable | MaterialRenderAssetsUnavailable;

package/render-assets-types.js

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

package/run-events.d.ts

@@ -47,9 +47,22 @@ export interface CompositionReviewCriteriaSuggestion {
     term?: string;
     score: number;
 }
+/** Exact UTF-16 passage retained from the brief; no page coordinate is implied. */
+export interface CompositionBriefCriterionSourceRef {
+    sourceId: string;
+    quote: string;
+    textRange: {
+        start: number;
+        end: number;
+        unit: "utf16";
+    };
+}
 export interface CompositionReviewCriteriaUnresolved {
     slotId: string;
+    /** Unresolved negative language requires an explicit review decision. */
+    polarity?: "exclusion";
     raw: string;
+    sourceRefs?: CompositionBriefCriterionSourceRef[];
     /**
      * Ranked corrections, best first. MG-994: every one of these is an attribute
      * the slot's own category holds accepted values for, so accepting the top

package/samplize-catalogue-types.d.ts

@@ -0,0 +1,92 @@
+export interface SamplizeCatalogueOptions {
+    limit?: number;
+    after?: string;
+    /** Pin every subsequent page to the version returned by the first page. */
+    sourceVersion?: string;
+}
+export interface SamplizeCatalogueProduct {
+    variantId: string;
+    productId: string;
+    name: string;
+    code: string;
+    brand: {
+        slug: string;
+        name: string;
+    };
+    hex: string;
+    hexSource: {
+        publisher: "Samplize";
+        url: string;
+        source: "snowflake_product_tags";
+    };
+    lrv: number | null;
+    lrvSource: SamplizeLrvObservation | null;
+    lrvObservations: SamplizeLrvObservation[];
+    /** The primary sample variant count, never an aggregate of product orders. */
+    demand: SamplizeDemand | null;
+    collectionMemberships: SamplizeCollectionMembership[];
+    colourAnalysis: Record<string, unknown>;
+    oklab: {
+        L: number;
+        a: number;
+        b: number;
+    };
+    sourceProductId: string;
+    url: string;
+    sizeVariants: Array<{
+        sourceVariantId: string;
+        sku: string | null;
+        title: string | null;
+        price: number | null;
+        inventoryAvailable: boolean;
+        demand: SamplizeDemand | null;
+    }>;
+    publishedHexes: SamplizeHexObservation[];
+    hexObservations: SamplizeHexObservation[];
+}
+export interface SamplizeCataloguePage {
+    schemaVersion: 2;
+    corpusScope: "samplizeCatalogue";
+    sourceVersion: string;
+    source: Record<string, unknown>;
+    total: number;
+    items: SamplizeCatalogueProduct[];
+    nextCursor: string | null;
+    /** True on the final page; completeness requires collecting total unique IDs. */
+    complete: boolean;
+}
+export interface SamplizeHexObservation {
+    hex: string;
+    publisher: string;
+    source: string;
+    sourceUrl: string | null;
+    sourceBasis: string;
+    observedAt: string | null;
+    differsFromSelected: boolean;
+}
+export interface SamplizePublicationSource {
+    publisher: "Samplize";
+    source: "algolia_shopify_products";
+    sourceUrl: string;
+    observedAt: string | null;
+}
+export interface SamplizeLrvObservation extends SamplizePublicationSource {
+    field: string;
+    value: number;
+}
+export interface SamplizeDemand extends SamplizePublicationSource {
+    field: "recently_ordered_count";
+    sourceVariantId: string;
+    grain: "shopify_variant";
+    recentlyOrderedCount: number;
+    /** The publisher does not supply the time window. */
+    window: null;
+}
+export interface SamplizeCollectionMembership {
+    sourceCollectionId: string;
+    handle: string;
+    url: string;
+    publisher: "Samplize";
+    source: "algolia_shopify_products";
+    observedAt: string | null;
+}

package/samplize-catalogue-types.js

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

package/samplize-colorvec.d.ts

@@ -0,0 +1,70 @@
+export declare const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
+export declare const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = "oklch-anchor-quantiles-v12";
+export interface SamplizeColorVecPaint {
+    variantId: string;
+    hex: string;
+    brand: string;
+    oklab: {
+        L: number;
+        a: number;
+        b: number;
+    };
+    family: string;
+    lightness: string;
+    intensity: string;
+    vector: number[] | string;
+}
+export interface SamplizeColorVecCache {
+    sourceVersion: string;
+    dictionaryVersion: string;
+    embeddingVersion: string;
+    rankingVersion: string;
+    generatedAt: string;
+    paints: SamplizeColorVecPaint[];
+}
+export interface SamplizeColorVecInput {
+    hex?: string;
+    reference?: string;
+    palette?: Array<{
+        hex: string;
+        proportion: number;
+    }>;
+    direction?: "similar" | "lighter" | "darker" | "muted";
+    brand?: string[];
+    family?: string[];
+    lightness?: string[];
+    intensity?: string[];
+    lightnessMin?: number;
+    lightnessMax?: number;
+    temperatureMin?: number;
+    temperatureMax?: number;
+    limit?: number;
+}
+export declare const samplizeSolidColorVector: (hex: string) => number[];
+/** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
+export declare function selectSamplizeEligiblePaints<T extends Omit<SamplizeColorVecPaint, "vector">>(paints: T[], input: SamplizeColorVecInput): {
+    reference: T | undefined;
+    eligible: T[];
+    counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
+};
+/** Official portable MG ranking over its complete versioned sampling-channel projection. */
+export declare function createSamplizeColorVecIndex(cache: SamplizeColorVecCache): {
+    search(input: SamplizeColorVecInput): {
+        ids: string[];
+        groups: {
+            hex: string;
+            proportion: number;
+            quota: number;
+            ids: string[];
+            shortfall: number;
+        }[];
+        limited: boolean;
+        eligibleCount: number;
+        counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
+        sourceVersion: string;
+        dictionaryVersion: string;
+        embeddingVersion: string;
+        rankingVersion: string;
+        countBasis: "complete-catalogue";
+    };
+};