@instruments/materialgraph 0.19.0 → 0.21.0

package/attribution-types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Result attribution (MG-1131) — joining an outcome back to the ranking that
+ * produced it.
+ *
+ * When someone orders a sample days after a search, a list of SKUs cannot say
+ * which response returned it or on what basis it was ranked. Store
+ * {@link SearchResultItem.resultId} next to the order row and
+ * {@link ResponseAttribution} beside the search, and both questions become a
+ * join in your own warehouse.
+ *
+ * MaterialGraph keeps no ledger of these ids. What you store IS the record.
+ */
+/**
+ * The ranking basis, in one vocabulary across both ranked routes.
+ *
+ * The first five values are `search()`'s `mode` verbatim, and there
+ * `attribution.basis === mode` always. `"match"` is what `match()` reports;
+ * that route has no `mode`, so this is the only field its outcomes can be
+ * grouped by.
+ */
+export type AttributionBasis = "image" | "colour" | "text" | "lexical" | "entity-browse" | "match";
+/**
+ * Envelope-level attribution receipt, on every successful ranked response.
+ *
+ * Store this beside the search and each result's `resultId` beside the outcome
+ * (an order, a save, a click), and "which sample was ordered off which ranking,
+ * on what basis" becomes a join in your own warehouse.
+ *
+ * A `resultId` is `<responseId>:<rank>`, rank being 1-based within the response
+ * that returned it — unique across pages, because each page is its own
+ * response. On the Match stream lane it also carries the surface id, so a hit
+ * sent twice (on its `surface` frame and again inside `complete`) keeps one key.
+ *
+ * Both ids are OPAQUE: store them verbatim, never parse them. Group on
+ * `responseId` and `basis`.
+ *
+ * Both fields are optional in the SDK types for one reason only: a server
+ * predating MG-1131 does not send them. Every current response does.
+ */
+export interface ResponseAttribution {
+    /**
+     * This response's stable id — the same value as the `X-Request-Id` header.
+     * Opaque: store it verbatim, never parse it. Group your stored outcomes by
+     * this field to recover the response that produced them.
+     */
+    responseId: string;
+    /** How this ranking was produced. The field to group outcomes by. */
+    basis: AttributionBasis;
+    /** ISO-8601 timestamp of when the response was assembled. */
+    issuedAt: string;
+}

package/attribution-types.js

@@ -0,0 +1,13 @@
+/**
+ * Result attribution (MG-1131) — joining an outcome back to the ranking that
+ * produced it.
+ *
+ * When someone orders a sample days after a search, a list of SKUs cannot say
+ * which response returned it or on what basis it was ranked. Store
+ * {@link SearchResultItem.resultId} next to the order row and
+ * {@link ResponseAttribution} beside the search, and both questions become a
+ * join in your own warehouse.
+ *
+ * MaterialGraph keeps no ledger of these ids. What you store IS the record.
+ */
+export {};

package/brand-most-sampled-types.d.ts

@@ -0,0 +1,33 @@
+import type { CandidateReadCard } from "./exploration-types.js";
+export interface BrandMostSampledResponse {
+    data: {
+        brand: {
+            id: string;
+            name: string;
+        };
+        status: "ready" | "unavailable";
+        metric: "sample_order_lines";
+        provenance: {
+            source: "material_bank_order_history";
+            signal: "sampled";
+            sessionId: string;
+            window: "trailing_36mo";
+            windowStart: string;
+            windowEnd: string;
+        } | null;
+        products: Array<{
+            rank: number;
+            sampleOrderLines: number;
+            representativeVariantSampleOrderLines: number;
+            card: CandidateReadCard & {
+                category: string | null;
+            };
+        }>;
+    };
+    meta: {
+        operationId: "brands.most_sampled";
+        requestId: string;
+    };
+    links: Record<string, never>;
+    warnings: never[];
+}

package/brand-most-sampled-types.js

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

package/by-colour-types.d.ts

@@ -99,6 +99,15 @@ export interface ColourFamilyGate {
      * once the page is cut to `limit`; this is the gate's own cost.
      */
     dropped: number;
+    /**
+     * Rows dropped a SECOND time, after the page was hydrated with the brand's
+     * declared `colour_hex`. A paint's chip photograph and its published hex are
+     * different colours and can fall in different families, so the page is
+     * re-gated on the hex it reports — every `hex` you receive belongs to the
+     * family you asked for. Absent means hydration moved nothing across a
+     * boundary.
+     */
+    droppedOnPublishedHex?: number;
 }
 /** Receipt for the hard category gate and its treatment of unknown typing. */
 export interface ColourCategoryGate {

package/catalogue-client.d.ts

@@ -1,11 +1,81 @@
+import type { BrandMostSampledResponse } from "./brand-most-sampled-types.js";
 import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueCollectionsOptions, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
+import type { CompareInput, CompareResponse } from "./compare-types.js";
+import type { CreateCorrectionInput, CorrectionResponse, CorrectionsListResponse } from "./correction-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
+import type { IdentifySelectedPageInput, IdentifySelectedPageResult } from "./identify-types.js";
 import type { SamplizeCatalogueOptions, SamplizeCataloguePage } from "./samplize-catalogue-types.js";
+import type { SamplizeColorVecCache } from "./samplize-colorvec.js";
 /** Catalogue publication operations inherited by the public SDK client. */
 export declare class CatalogueClient {
     #private;
     protected constructor(transport: HttpTransport);
+    /** Brand products ranked by observed Material Bank sample-order lines, with window provenance. */
+    brandMostSampled(brandId: string, options?: {
+        limit?: number;
+    }, signal?: AbortSignal): Promise<BrandMostSampledResponse>;
+    /** Compare canonical Variants without searching or ranking them. */
+    compare(input: CompareInput, signal?: AbortSignal): Promise<CompareResponse>;
+    /** Submit confirmed caller-authored review work; never changes accepted truth. */
+    createCorrection(input: CreateCorrectionInput, options: {
+        idempotencyKey: string;
+        signal?: AbortSignal;
+    }): Promise<CorrectionResponse>;
+    getCorrection(correctionId: string, signal?: AbortSignal): Promise<CorrectionResponse>;
+    listCorrections(input?: {
+        cursor?: string;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<CorrectionsListResponse>;
+    /** Identify the canonical graph subject for one explicitly selected page. */
+    identify(input: IdentifySelectedPageInput, signal?: AbortSignal): Promise<IdentifySelectedPageResult>;
+    /** Complete producer-owned vectors and classifications for portable colour matching. */
+    samplizeColorVecCache(sourceVersion: string, signal?: AbortSignal): Promise<SamplizeColorVecCache>;
+    /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */
+    samplizeCatalogueSearch(input: {
+        palette?: Array<{
+            hex: string;
+            proportion: number;
+        }>;
+        query?: string;
+        reference?: string;
+        direction?: "similar" | "lighter" | "darker" | "muted";
+        lightnessMin?: number;
+        lightnessMax?: number;
+        temperatureMin?: number;
+        temperatureMax?: number;
+        family?: string[];
+        lightness?: string[];
+        intensity?: string[];
+        brand?: string[];
+        sourceVersion: string;
+        limit?: number;
+    }, signal?: AbortSignal): Promise<{
+        target?: {
+            ref: string;
+            hex: string;
+            name?: string;
+            source: string;
+            confidence?: number;
+        };
+        embeddingVersion?: string;
+        rankingVersion?: string;
+        dictionaryVersion?: string;
+        eligibleCount?: number;
+        groups?: Array<{
+            hex: string;
+            proportion: number;
+            quota: number;
+            ids: string[];
+            shortfall: number;
+        }>;
+        ids: string[];
+        limited: boolean;
+        sourceVersion: string;
+        counts: Record<string, Record<string, number>>;
+        countBasis: string;
+        basis: string;
+    }>;
     /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
     samplizeCatalogue(options?: SamplizeCatalogueOptions, signal?: AbortSignal): Promise<SamplizeCataloguePage>;
     /**

package/catalogue-client.js

@@ -5,6 +5,50 @@ export class CatalogueClient {
     constructor(transport) {
         this.#transport = transport;
     }
+    /** Brand products ranked by observed Material Bank sample-order lines, with window provenance. */
+    brandMostSampled(brandId, options = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("brands.most_sampled"), { query: { brandId, ...options }, signal });
+    }
+    /** Compare canonical Variants without searching or ranking them. */
+    compare(input, signal) {
+        return this.#transport.requestJson(resolveOperation("retrieval.compare"), {
+            body: input,
+            signal,
+        });
+    }
+    /** Submit confirmed caller-authored review work; never changes accepted truth. */
+    createCorrection(input, options) {
+        if (!/^[\x21-\x7e]{1,200}$/.test(options.idempotencyKey))
+            throw new Error("A valid Idempotency-Key is required for Correction submission.");
+        return this.#transport.requestJson(resolveOperation("corrections.create"), {
+            body: input,
+            ...options,
+        });
+    }
+    getCorrection(correctionId, signal) {
+        return this.#transport.requestJson(resolveOperation("corrections.get"), {
+            pathParams: { correctionId },
+            signal,
+        });
+    }
+    listCorrections(input = {}, signal) {
+        return this.#transport.requestJson(resolveOperation("corrections.list"), {
+            query: input,
+            signal,
+        });
+    }
+    /** Identify the canonical graph subject for one explicitly selected page. */
+    identify(input, signal) {
+        return this.#transport.requestJson(resolveOperation("retrieval.identify"), { body: input, signal });
+    }
+    /** Complete producer-owned vectors and classifications for portable colour matching. */
+    samplizeColorVecCache(sourceVersion, signal) {
+        return this.#transport.requestJson(resolveOperation("samplize_colorvec_cache"), { query: { sourceVersion }, signal });
+    }
+    /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */
+    samplizeCatalogueSearch(input, signal) {
+        return this.#transport.requestJson(resolveOperation("samplize_catalogue_search"), { body: input, signal });
+    }
     /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
     samplizeCatalogue(options = {}, signal) {
         return this.#transport.requestJson(resolveOperation("samplize_catalogue_products"), { query: { ...options }, signal });

package/colours-client.d.ts

@@ -1,3 +1,6 @@
+import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsParams, ColourStatsResponse } from "./colour-aggregate-types.js";
+import type { QueryParams } from "./http-transport.js";
+import type { SdkOperationId } from "./operations.js";
 /**
  * The colour surface, namespaced as `mg.colours` — the aggregate reads
  * (`stats`, `profiles`) plus MULTI-COLOUR search (`palette`, `gradient`).
@@ -32,9 +35,7 @@
  * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
  * likeness, never a stated colour specification.
  */
-import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsParams, ColourStatsResponse } from "./colour-aggregate-types.js";
-import type { QueryParams } from "./http-transport.js";
-import type { SdkOperationId } from "./operations.js";
+import type { PaletteCompleteInput, PaletteCompleteResponse, PaletteDiscoverInput, PaletteDiscoverResponse } from "./palette-completion-types.js";
 import type { SearchGradientInput, SearchGradientResponse, SearchPaletteInput, SearchPaletteResponse } from "./palette-search-types.js";
 /** The client's own request primitives, handed down so this file owns no transport. */
 export interface ColoursTransport {
@@ -44,6 +45,10 @@ export interface ColoursTransport {
 export declare class ColoursClient {
     #private;
     constructor(transport: ColoursTransport);
+    /** Complete exact retained colors against a shared published interior reference. No Cart mutation. */
+    complete(input: PaletteCompleteInput, signal?: AbortSignal): Promise<PaletteCompleteResponse>;
+    /** Browse diverse published interior compositions against a version-pinned eligible catalogue. */
+    discover(input: PaletteDiscoverInput, signal?: AbortSignal): Promise<PaletteDiscoverResponse>;
     /**
      * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
      * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).

package/colours-client.js

@@ -3,6 +3,14 @@ export class ColoursClient {
     constructor(transport) {
         this.#transport = transport;
     }
+    /** Complete exact retained colors against a shared published interior reference. No Cart mutation. */
+    complete(input, signal) {
+        return this.#transport.post("complete_interior_palette", input, signal);
+    }
+    /** Browse diverse published interior compositions against a version-pinned eligible catalogue. */
+    discover(input, signal) {
+        return this.#transport.get("discover_interior_palettes", { ...input }, signal);
+    }
     /**
      * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
      * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).

package/compare-types.d.ts

@@ -0,0 +1,89 @@
+export interface CompareInput {
+    variantIds: string[];
+    selection?: {
+        kind: "blocks";
+        blockIds: string[];
+    } | {
+        kind: "attributes";
+        attributeIds: string[];
+    };
+}
+type Availability = "available" | "discontinued" | "superseded" | "unknown";
+type ClaimScope = "variant" | "product" | "brand";
+export interface CompareTarget {
+    variantId: string;
+    version: string;
+    freshness: {
+        oldestAt: string | null;
+        newestAt: string | null;
+    };
+    identity: {
+        variantId: string;
+        variantName: string | null;
+        brand: string;
+        brandSlug: string;
+        product: string;
+        productId: string;
+        colourName: string | null;
+        category: string | null;
+        categoryPath: string[];
+        imageUrl: string | null;
+        installationImageUrl: string | null;
+        dominantHex: string | null;
+        siblingCount: number;
+    };
+    availability: {
+        state: Availability;
+        label: string | null;
+        supersededBy: {
+            variantId: string;
+            brandSlug: string;
+            productId: string;
+            brand: string;
+            product: string;
+            variant: string;
+            color: string | null;
+            availability: Availability;
+        } | null;
+    };
+    sampleability: boolean | null;
+}
+export interface CompareCell {
+    variantId: string;
+    state: "known" | "unknown" | "conflicting" | "inapplicable";
+    recordState: "stated" | "conflicting" | "stale" | "unknown" | "missing" | "not_applicable" | "not_evaluated";
+    value: unknown;
+    unit: string | null;
+    verification: "verified" | "unverified" | "unbacked";
+    confidence: number | null;
+    sourceBasis: string | null;
+    sourceRef: string | null;
+    freshnessAt: string | null;
+    claimScope: ClaimScope | null;
+    competingClaims: {
+        scope: ClaimScope;
+        value: unknown;
+        sourceRef: string | null;
+    }[];
+}
+export interface CompareResult {
+    targets: CompareTarget[];
+    rows: {
+        blockId: string;
+        blockName: string;
+        attributeId: string;
+        label: string;
+        outcome: "same" | "different" | "incomplete" | "indeterminate" | "not_applicable";
+        cells: CompareCell[];
+    }[];
+}
+export interface CompareResponse {
+    data: CompareResult;
+    meta: {
+        operationId: "retrieval.compare";
+        requestId: string;
+    };
+    links: Record<string, never>;
+    warnings: never[];
+}
+export {};

package/compare-types.js

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

package/correction-types.d.ts

@@ -0,0 +1,88 @@
+export type CorrectionJson = null | boolean | number | string | CorrectionJson[] | {
+    [key: string]: CorrectionJson;
+};
+export type CorrectionSubject = {
+    kind: "brand" | "product" | "variant";
+    id: string;
+};
+export type CorrectionTarget = {
+    kind: "identity";
+    subject: CorrectionSubject;
+} | {
+    kind: "attribute";
+    subject: CorrectionSubject;
+    blockId: string;
+    attributeId: string;
+} | {
+    kind: "relationship";
+    subject: CorrectionSubject;
+    relationship: string;
+    relatedSubject: CorrectionSubject;
+} | {
+    kind: "source_interpretation";
+    sourceMaterialId: string;
+    subject?: CorrectionSubject;
+} | {
+    kind: "missing_record";
+    url: string;
+};
+/** Caller-supplied evidence is not an independently verified graph reading. */
+export interface CorrectionEvidence {
+    state: "known" | "unknown" | "conflicting" | "not_applicable";
+    value?: CorrectionJson;
+    sourceUrl?: string;
+    note?: string;
+}
+export interface CreateCorrectionInput {
+    target: CorrectionTarget;
+    pageEvidence: CorrectionEvidence;
+    graphEvidence: CorrectionEvidence;
+    proposedChange: CorrectionJson;
+    rationale: string;
+}
+export interface Correction {
+    id: string;
+    submission: CreateCorrectionInput;
+    status: "submitted" | "in_review" | "resolved" | "withdrawn";
+    resolution: "substantiated" | "not_substantiated" | "duplicate" | "superseded" | "cannot_determine" | null;
+    createdAt: string;
+    updatedAt: string;
+    acceptedTruthChanged: false;
+}
+export interface CorrectionResponse {
+    data: Correction;
+    meta: {
+        operationId: "corrections.create";
+        requestId: string;
+        idempotency: {
+            replayed: boolean;
+        };
+    } | {
+        operationId: "corrections.get";
+        requestId: string;
+    };
+    links: {
+        self: string;
+    };
+    warnings: never[];
+}
+export interface CorrectionsListResponse {
+    data: Correction[];
+    meta: {
+        operationId: "corrections.list";
+        requestId: string;
+        page: {
+            returned: number;
+            total: {
+                value: null;
+                basis: "unavailable";
+            };
+            nextCursor: string | null;
+        };
+    };
+    links: {
+        self: string;
+        next: string | null;
+    };
+    warnings: never[];
+}

package/correction-types.js

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

package/exploration-types.d.ts

@@ -18,6 +18,7 @@ export interface GraphOperatorEvidence {
 export interface CandidateReadInput {
     operator: "looks_like";
     corpusScope?: CorpusScope;
+    /** Return up to 24 ranked candidates (default 8), from one bounded retrieval. */
     limit?: number;
     excludeVariantIds?: VariantId[];
 }

package/http-transport.d.ts

@@ -11,6 +11,8 @@ import { type SdkOperation } from "./operations.js";
 export type QueryValue = string | number | boolean | undefined | null | Array<string | number | boolean>;
 export type QueryParams = Record<string, QueryValue>;
 export interface RequestOptions {
+    /** Required by state-changing operations that support safe retries. */
+    idempotencyKey?: string;
     query?: QueryParams;
     body?: unknown;
     signal?: AbortSignal;

package/http-transport.js

@@ -211,7 +211,12 @@ export class HttpTransport {
         const { parsed } = await this.send({
             method: sdkOperation.method,
             url,
-            headers: this.authHeaders(hasBody ? { "Content-Type": "application/json" } : undefined),
+            headers: this.authHeaders({
+                ...(hasBody ? { "Content-Type": "application/json" } : {}),
+                ...(options.idempotencyKey
+                    ? { "Idempotency-Key": options.idempotencyKey }
+                    : {}),
+            }),
             body: hasBody ? JSON.stringify(options.body) : undefined,
             signal: options.signal,
         });

package/identify-types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Public wire types for `POST /api/v1/identify`.
+ *
+ * These intentionally mirror the domain-owned Zod contract rather than
+ * importing it: the published SDK must carry no workspace package dependency.
+ */
+export interface IdentifySelectedPageInput {
+    url: string;
+    title?: string;
+    selectedText?: string;
+    productLabels?: string[];
+    brandLabels?: string[];
+    /** Manufacturer code visibly supplied by the selected page. */
+    manufacturerCode?: string;
+    imageUrls?: string[];
+    colourHexes?: string[];
+}
+export interface IdentifySelectedPageSubject {
+    kind: "variant" | "product" | "brand";
+    id: string;
+    name: string;
+    brand?: {
+        id: string;
+        name: string;
+        slug: string;
+    };
+}
+export interface IdentifySelectedPageEvidence {
+    kind: "manufacturer-url" | "brand-homepage" | "visible-identity" | "visual" | "colour";
+    url?: string;
+    detail: string;
+}
+interface IdentifySelectedPageDataBase {
+    receipt: {
+        submittedUrl: string;
+        normalizedUrl: string;
+        normalizationSteps: string[];
+    };
+    evidence: IdentifySelectedPageEvidence[];
+}
+export type IdentifySelectedPageData = (IdentifySelectedPageDataBase & {
+    outcome: "identified";
+    rung: "lookup" | "disambiguate";
+    subject: IdentifySelectedPageSubject & {
+        kind: "variant";
+    };
+}) | (IdentifySelectedPageDataBase & {
+    outcome: "placed";
+    rung: "lookup";
+    subject: IdentifySelectedPageSubject & {
+        kind: "product" | "brand";
+    };
+}) | (IdentifySelectedPageDataBase & {
+    outcome: "ambiguous";
+    rung: "lookup" | "disambiguate" | "match" | "color";
+    candidates: IdentifySelectedPageSubject[];
+    truncated: boolean;
+}) | (IdentifySelectedPageDataBase & {
+    outcome: "unresolved";
+    rung?: "match" | "color";
+});
+/** The canonical callable-operation envelope returned by `identify()`. */
+export interface IdentifySelectedPageResult {
+    data: IdentifySelectedPageData;
+    meta: {
+        operationId: "retrieval.identify";
+        requestId: string;
+    };
+    links: Record<string, never>;
+    warnings: [];
+}
+export {};

package/identify-types.js

@@ -0,0 +1,7 @@
+/**
+ * Public wire types for `POST /api/v1/identify`.
+ *
+ * These intentionally mirror the domain-owned Zod contract rather than
+ * importing it: the published SDK must carry no workspace package dependency.
+ */
+export {};

package/index.d.ts

@@ -1,4 +1,6 @@
 export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.js";
+export type { CompareInput, CompareTarget, CompareCell, CompareResult, CompareResponse, } from "./compare-types.js";
+export type { CorrectionJson, CorrectionSubject, CorrectionTarget, CorrectionEvidence, CreateCorrectionInput, Correction, CorrectionResponse, CorrectionsListResponse, } from "./correction-types.js";
 export type { MaterialGraphClientOptions, BrowseNamespace, ExplorationNamespace, SourceMaterialCommentsNamespace, } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
@@ -19,7 +21,9 @@ export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
 export type * from "./search-collapse-types.js";
+export type * from "./search-card-types.js";
 export type * from "./match-types.js";
+export type * from "./identify-types.js";
 export type * from "./browse-types.js";
 export type * from "./catalogue-types.js";
 export type * from "./by-colour-types.js";
@@ -45,7 +49,10 @@ export type * from "./schedule-reference-types.js";
 export type * from "./substitute-types.js";
 export type * from "./search-refinement-types.js";
 export type * from "./search-window-types.js";
+export type * from "./attribution-types.js";
 export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
 export type * from "./spec-types.js";
 export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specRangeCriterion, specTerm, } from "./specifications.js";
 export type { SamplizePublicationSource, SamplizeLrvObservation, SamplizeDemand, SamplizeCollectionMembership, SamplizeCatalogueOptions, SamplizeCataloguePage, SamplizeCatalogueProduct, SamplizeHexObservation, } from "./samplize-catalogue-types.js";
+export type { PaletteCompleteInput, PaletteCompleteResponse, PaletteDiscoverInput, PaletteDiscoverResponse, } from "./palette-completion-types.js";
+export type { BrandMostSampledResponse } from "./brand-most-sampled-types.js";

package/match-stream-types.d.ts

@@ -1,3 +1,4 @@
+import type { ResponseAttribution } from "./attribution-types.js";
 import type { MatchCategoryInference, MatchColourReading } from "./match-types.js";
 /**
  * The Material Match PROGRESS-STREAM contracts — the wire vocabulary of
@@ -179,6 +180,18 @@ export type MatchSenseCheckVerdict = (typeof MATCH_SENSE_CHECK_VERDICTS)[number]
 export declare const MATCH_OUTCOMES: readonly ["matched", "no_surfaces"];
 export type MatchOutcome = (typeof MATCH_OUTCOMES)[number];
 export interface MatchWorkflowResult {
+    /**
+     * Result attribution (MG-1131) — `responseId` (the same value as the run's
+     * `X-Request-Id` header), `basis: "match"`, and `issuedAt`. Every item in
+     * `results` and in each `surfaces[].results` carries a matching `resultId`.
+     *
+     * A surface's hits arrive twice — on its own `surface` frame and again here —
+     * and both times with the SAME `resultId`, so a consumer that stored the
+     * first recognises the second rather than double-counting it.
+     *
+     * ABSENT only from a response produced by a server predating MG-1131.
+     */
+    attribution?: ResponseAttribution;
     imageType: MatchImageType;
     /** How the run ended. Absent means `matched`. */
     outcome?: MatchOutcome;