@instruments/materialgraph 0.24.0 → 0.26.0

package/exploration-types.d.ts

@@ -1,7 +1,7 @@
 import type { CorpusScope, CorpusScopeReceipt } from "./corpus-scope-types.js";
 import type { VariantId } from "./identifiers.js";
 export type GraphOperator = "colourways" | "same_category" | "still_listed" | "looks_like" | "same_colour" | "pairs_with" | "often_specified_with" | "substitutes_for" | "more_durable" | "outdoor_suitable" | "lower_cost" | "more_sustainable";
-export interface GraphOperatorAvailability {
+export type GraphOperatorAvailability = {
     operator: GraphOperator;
     operatorClass: "identity" | "perceptual" | "relational" | "spec";
     label: string;
@@ -10,30 +10,30 @@ export interface GraphOperatorAvailability {
     discoverable: boolean;
     discoveryBasis: string;
     count?: number;
-}
-export interface GraphOperatorEvidence {
+};
+export type GraphOperatorEvidence = {
     variantId: VariantId;
     operators: GraphOperatorAvailability[];
-}
-export interface CandidateReadInput {
+};
+export type CandidateReadInput = {
     operator: "looks_like";
     corpusScope?: CorpusScope;
     /** Return up to 24 ranked candidates (default 8), from one bounded retrieval. */
     limit?: number;
     excludeVariantIds?: VariantId[];
-}
-export interface CandidateReadImage {
+};
+export type CandidateReadImage = {
     url: string;
     source: "r2" | "origin";
     /** Null means this image has not been analysed for a uniform light background. */
     isIsolated: boolean | null;
-}
-export interface CandidateReadPaletteSwatch {
+};
+export type CandidateReadPaletteSwatch = {
     hex: string;
     proportion: number;
     name?: string | null;
-}
-export interface CandidateReadCard {
+};
+export type CandidateReadCard = {
     variantId: VariantId;
     productId: string;
     brandSlug: string;
@@ -44,27 +44,27 @@ export interface CandidateReadCard {
     color: string | null;
     image: CandidateReadImage | null;
     palette: CandidateReadPaletteSwatch[];
-}
-export interface CandidateRankEvidence {
+};
+export type CandidateRankEvidence = {
     rank: number;
     distance: number;
     similarity: number;
     basis: "active_main_image_embedding";
     provenanceGrade: "measured";
     displayImageMatchedEvidence: boolean | null;
-}
-export interface CandidateReadCandidate extends CandidateReadCard {
+};
+export type CandidateReadCandidate = {
     evidence: CandidateRankEvidence;
     reason: string;
-}
-export interface CandidateSeedEvidence {
+} & CandidateReadCard;
+export type CandidateSeedEvidence = {
     evidenceImageSha256: string;
     displayImageSha256: string | null;
     basis: "active_main_image_embedding";
     provenanceGrade: "measured";
     displayImageMatchedEvidence: boolean | null;
-}
-export interface CandidateReadReceipt {
+};
+export type CandidateReadReceipt = {
     operator: "looks_like";
     corpusScope: CorpusScopeReceipt | null;
     requestedLimit: number;
@@ -77,6 +77,13 @@ export interface CandidateReadReceipt {
     dedupe: {
         retrieved: number;
         removed: number;
+        /**
+         * How many of `removed` went because an earlier row showed the SAME
+         * PICTURE, counted apart from the id rules (MG-1917). Distinct products
+         * routinely share one photograph, so an id-only collapse returned the same
+         * image several times on one page.
+         */
+        removedBySharedImage: number;
         truncated: number;
         projectionMisses: number;
     };
@@ -87,11 +94,11 @@ export interface CandidateReadReceipt {
         projectionMs: number;
         completeMs: number;
     };
-}
-interface CandidateReadResponseBase {
+};
+type CandidateReadResponseBase = {
     seed: CandidateReadCard;
     receipt: CandidateReadReceipt;
-}
+};
 export type CandidateReadResponse = (CandidateReadResponseBase & {
     status: "ready";
     seedEvidence: CandidateSeedEvidence;

package/fan-deck-types.d.ts

@@ -6,7 +6,7 @@
  * while holding one page of each. So the response carries the brand, and
  * `truncatedAt` appears only if a range ever exceeds the server's ceiling.
  */
-export interface FanDeckSwatch {
+export type FanDeckSwatch = {
     /** Opaque token. Never parse or construct one. */
     variantId: string;
     brand: string;
@@ -19,13 +19,13 @@ export interface FanDeckSwatch {
     /** OKLab L, 0–1. The sort key within a family: light to dark. */
     lightness: number;
     imageUrl: string | null;
-}
-export interface FanDeckFamily {
+};
+export type FanDeckFamily = {
     family: string;
     /** Count over the WHOLE range, computed before any truncation. */
     count: number;
-}
-export interface BrandFanDeck {
+};
+export type BrandFanDeck = {
     /**
      * The brand SLUGS the deck resolved to — round-trippable identifiers, not
      * display names. The maker's name as it should be shown is on every swatch.
@@ -39,4 +39,4 @@ export interface BrandFanDeck {
      * deck is complete — absent is not zero.
      */
     truncatedAt?: number;
-}
+};

package/http-transport.d.ts

@@ -1,48 +1,40 @@
-/**
- * The shared low-level HTTP transport for {@link MaterialGraphClient}. It owns
- * URL building, the bearer header, rate-limit capture, response reading, and the
- * one error-mapping path — so the JSON read surface (`client.ts`), the multipart
- * upload, the SSE stream (`runs.ts`), and the NDJSON Match stream
- * (`match-stream.ts`) all fail identically. Retry-free by design; a single
- * failure surfaces as one {@link MaterialGraphError}.
- */
-import { type RateLimit } from "./errors.js";
-import { type SdkOperation } from "./operations.js";
-export type QueryValue = string | number | boolean | undefined | null | Array<string | number | boolean>;
+import type { RateLimit } from "./errors.js";
+import type { SdkOperation } from "./operations.js";
+export type QueryValue = string | number | boolean | undefined | null | (string | number | boolean)[];
 export type QueryParams = Record<string, QueryValue>;
-export interface RequestOptions {
+export type RequestOptions = {
     /** Required by state-changing operations that support safe retries. */
     idempotencyKey?: string;
     query?: QueryParams;
     body?: unknown;
     signal?: AbortSignal;
     pathParams?: Readonly<Record<string, string>>;
-}
-export interface StreamRequestOptions extends RequestOptions {
+};
+export type StreamRequestOptions = {
     /** The streaming media type to negotiate (`text/event-stream`, `application/x-ndjson`). */
     accept: string;
     /** Names this stream in the "returned no body" diagnostic, e.g. `"match stream"`. */
     subject: string;
-}
+} & RequestOptions;
 /** A read, status-checked HTTP response with its parsed body. */
-export interface SentResponse {
+export type SentResponse = {
     response: Response;
     text: string;
     parsed: unknown;
-}
-interface SendInput {
+};
+type SendInput = {
     method: string;
     url: string;
     headers: Record<string, string>;
     /** The only bodies the SDK sends: a JSON string or a multipart `FormData`. */
     body?: string | FormData;
     signal?: AbortSignal;
-}
-export interface HttpTransportOptions {
+};
+export type HttpTransportOptions = {
     apiKey: string;
     baseUrl: string;
     fetch: typeof fetch;
-}
+};
 export declare class HttpTransport {
     #private;
     readonly baseUrl: string;

package/http-transport.js

@@ -8,13 +8,14 @@
  */
 import { MaterialGraphError } from "./errors.js";
 import { operationPath } from "./operations.js";
-function parseIntOrNull(value) {
-    if (value === null)
+const parseIntOrNull = (value) => {
+    if (value === null) {
         return null;
+    }
     const parsed = Number.parseInt(value, 10);
     return Number.isNaN(parsed) ? null : parsed;
-}
-function parseRateLimit(headers) {
+};
+const parseRateLimit = (headers) => {
     const limit = parseIntOrNull(headers.get("x-ratelimit-limit"));
     const remaining = parseIntOrNull(headers.get("x-ratelimit-remaining"));
     const reset = parseIntOrNull(headers.get("x-ratelimit-reset"));
@@ -26,7 +27,7 @@ function parseRateLimit(headers) {
         return null;
     }
     return { limit, remaining, reset, retryAfter };
-}
+};
 export class HttpTransport {
     baseUrl;
     apiKey;
@@ -34,7 +35,7 @@ export class HttpTransport {
     #lastRateLimit = null;
     constructor(options) {
         this.apiKey = options.apiKey;
-        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.baseUrl = options.baseUrl.replace(/\/+$/u, "");
         this.fetch = options.fetch;
     }
     get lastRateLimit() {
@@ -43,8 +44,8 @@ export class HttpTransport {
     /** The bearer + JSON `Accept` headers, plus any per-request additions. */
     authHeaders(extra) {
         return {
-            Authorization: `Bearer ${this.apiKey}`,
             Accept: "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
             ...extra,
         };
     }
@@ -52,12 +53,14 @@ export class HttpTransport {
         const url = new URL(`${this.baseUrl}${path}`);
         if (query) {
             for (const [key, value] of Object.entries(query)) {
-                if (value === undefined || value === null)
+                if (value === undefined || value === null) {
                     continue;
+                }
                 if (Array.isArray(value)) {
                     for (const item of value) {
-                        if (item !== undefined && item !== null)
+                        if (item !== undefined && item !== null) {
                             url.searchParams.append(key, String(item));
+                        }
                     }
                 }
                 else {
@@ -83,17 +86,17 @@ export class HttpTransport {
         let response;
         try {
             response = await this.fetch(input.url, {
-                method: input.method,
-                headers: input.headers,
                 body: input.body,
+                headers: input.headers,
+                method: input.method,
                 signal: input.signal,
             });
         }
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                cause,
                 callerSignal: input.signal,
+                cause,
             });
         }
         const rateLimit = parseRateLimit(response.headers);
@@ -105,8 +108,8 @@ export class HttpTransport {
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                cause,
                 callerSignal: input.signal,
+                cause,
             });
         }
         let parsed;
@@ -121,15 +124,15 @@ export class HttpTransport {
         if (!response.ok) {
             throw MaterialGraphError.fromResponse({
                 ...metadata,
-                status: response.status,
-                body: parsed,
-                responseText: text,
-                rateLimit,
                 apiKey: this.apiKey,
+                body: parsed,
                 queryValues: [...requestUrl.searchParams.values()],
+                rateLimit,
+                responseText: text,
+                status: response.status,
             });
         }
-        return { response, text, parsed };
+        return { parsed, response, text };
     }
     /**
      * Open a streaming operation and hand back its UNREAD byte body — the one
@@ -152,20 +155,20 @@ export class HttpTransport {
         let response;
         try {
             response = await this.fetch(url, {
-                method: sdkOperation.method,
+                body: hasBody ? JSON.stringify(options.body) : undefined,
                 headers: this.authHeaders({
                     Accept: options.accept,
                     ...(hasBody ? { "Content-Type": "application/json" } : {}),
                 }),
-                body: hasBody ? JSON.stringify(options.body) : undefined,
+                method: sdkOperation.method,
                 signal: options.signal,
             });
         }
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                cause,
                 callerSignal: options.signal,
+                cause,
             });
         }
         const rateLimit = parseRateLimit(response.headers);
@@ -191,12 +194,12 @@ export class HttpTransport {
             }
             throw MaterialGraphError.fromResponse({
                 ...metadata,
-                status: response.status,
-                body: parsed,
-                responseText: text,
-                rateLimit,
                 apiKey: this.apiKey,
+                body: parsed,
                 queryValues: [...requestUrl.searchParams.values()],
+                rateLimit,
+                responseText: text,
+                status: response.status,
             });
         }
         if (response.body === null) {
@@ -209,16 +212,16 @@ export class HttpTransport {
         const url = this.buildUrl(operationPath(sdkOperation, options.pathParams), options.query);
         const hasBody = options.body !== undefined;
         const { parsed } = await this.send({
-            method: sdkOperation.method,
-            url,
+            body: hasBody ? JSON.stringify(options.body) : undefined,
             headers: this.authHeaders({
                 ...(hasBody ? { "Content-Type": "application/json" } : {}),
                 ...(options.idempotencyKey
                     ? { "Idempotency-Key": options.idempotencyKey }
                     : {}),
             }),
-            body: hasBody ? JSON.stringify(options.body) : undefined,
+            method: sdkOperation.method,
             signal: options.signal,
+            url,
         });
         return parsed;
     }

package/identify-types.d.ts

@@ -4,7 +4,7 @@
  * These intentionally mirror the domain-owned Zod contract rather than
  * importing it: the published SDK must carry no workspace package dependency.
  */
-export interface IdentifySelectedPageInput {
+export type IdentifySelectedPageInput = {
     url: string;
     title?: string;
     selectedText?: string;
@@ -14,8 +14,8 @@ export interface IdentifySelectedPageInput {
     manufacturerCode?: string;
     imageUrls?: string[];
     colourHexes?: string[];
-}
-export interface IdentifySelectedPageSubject {
+};
+export type IdentifySelectedPageSubject = {
     kind: "variant" | "product" | "brand";
     id: string;
     name: string;
@@ -24,20 +24,20 @@ export interface IdentifySelectedPageSubject {
         name: string;
         slug: string;
     };
-}
-export interface IdentifySelectedPageEvidence {
+};
+export type IdentifySelectedPageEvidence = {
     kind: "manufacturer-url" | "brand-homepage" | "visible-identity" | "visual" | "colour";
     url?: string;
     detail: string;
-}
-interface IdentifySelectedPageDataBase {
+};
+type IdentifySelectedPageDataBase = {
     receipt: {
         submittedUrl: string;
         normalizedUrl: string;
         normalizationSteps: string[];
     };
     evidence: IdentifySelectedPageEvidence[];
-}
+};
 export type IdentifySelectedPageData = (IdentifySelectedPageDataBase & {
     outcome: "identified";
     rung: "lookup" | "disambiguate";
@@ -60,7 +60,7 @@ export type IdentifySelectedPageData = (IdentifySelectedPageDataBase & {
     rung?: "match" | "color";
 });
 /** The canonical callable-operation envelope returned by `identify()`. */
-export interface IdentifySelectedPageResult {
+export type IdentifySelectedPageResult = {
     data: IdentifySelectedPageData;
     meta: {
         operationId: "retrieval.identify";
@@ -68,5 +68,5 @@ export interface IdentifySelectedPageResult {
     };
     links: Record<string, never>;
     warnings: [];
-}
+};
 export {};

package/index.d.ts

@@ -8,15 +8,10 @@ export type * from "./identifiers.js";
 export type * from "./exploration-types.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export type * from "./run-types.js";
-export type * from "./schedule-types.js";
 export type * from "./citation-types.js";
 export { VARY_AXES } from "./composition-types.js";
 export type * from "./composition-types.js";
 export type * from "./slot-pool-types.js";
-export { PROJECT_EVENT_KINDS } from "./project-types.js";
-export type * from "./project-types.js";
-export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
-export type * from "./run-events.js";
 export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
@@ -45,7 +40,6 @@ export type * from "./render-assets-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
 export type * from "./taxonomy-coverage-types.js";
-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";

package/index.js

@@ -2,8 +2,6 @@ export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS, } from "./client.
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 export { VARY_AXES } from "./composition-types.js";
-export { PROJECT_EVENT_KINDS } from "./project-types.js";
-export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
 export { MATERIALGRAPH_PROBLEM_EXTENSIONS, MaterialGraphError, } from "./errors.js";
 export { MATCH_IMAGE_TYPES, MATCH_OUTCOMES, MATCH_MATERIAL_FUNCTIONS, MATCH_STREAM_EVENT_TYPES, MATCH_SURFACE_STATUSES, MATCH_WORKFLOW_STEPS, } from "./match-stream-types.js";
 export { CodesClient } from "./codes-client.js";

package/match-rejection-types.d.ts

@@ -4,7 +4,7 @@
  * never a catalogue correction; wrong facts about a product go through
  * `createCorrection`.
  */
-export interface RejectMatchResultInput {
+export type RejectMatchResultInput = {
     /**
      * The surface the result was shown under - `surfaces[].surface.id` on a scene
      * match. Omit it for a result from the run-level `results` list.
@@ -14,9 +14,9 @@ export interface RejectMatchResultInput {
     variantId: string;
     /** Optional free text, up to 500 characters. Stored as given. */
     reason?: string;
-}
+};
 /** The receipt for one rejection. A repeat of the same rejection returns the original. */
-export interface MatchRejection {
+export type MatchRejection = {
     rejectionId: string;
     /** The match response's `attribution.responseId`. */
     responseId: string;
@@ -28,9 +28,9 @@ export interface MatchRejection {
     reason: string | null;
     /** ISO-8601. */
     rejectedAt: string;
-}
+};
 /** One match response and every rejection recorded against it. */
-export interface MatchRejectionList {
+export type MatchRejectionList = {
     responseId: string;
     /** `stream` for a scene match, `buffered` for the single-image JSON response. */
     lane: "buffered" | "stream";
@@ -40,4 +40,4 @@ export interface MatchRejectionList {
     resultCount: number;
     /** Oldest first. Empty means nothing was rejected. */
     rejections: MatchRejection[];
-}
+};