@instruments/materialgraph 0.44.0 → 0.46.0

package/client-config.d.ts

@@ -12,4 +12,11 @@ export type MaterialGraphClientOptions = {
     baseUrl?: string;
     /** Inject a custom `fetch` (tests, proxies). Defaults to the global `fetch`. */
     fetch?: typeof fetch;
+    /**
+     * Deadline in milliseconds for each request, composed with any signal the
+     * caller passes. An expired deadline throws a `MaterialGraphError` of kind
+     * `timeout`. It does not apply to run-event streams, which stay open until
+     * they end or the caller aborts. Absent means no deadline.
+     */
+    timeoutMs?: number;
 };

package/client.js

@@ -97,6 +97,9 @@ export class MaterialGraphClient extends CatalogueClient {
             apiKey: options.apiKey,
             baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
             fetch: options.fetch ?? globalThis.fetch,
+            ...(options.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: options.timeoutMs }),
         });
         super(transport);
         this.#transport = transport;

package/errors.d.ts

@@ -26,6 +26,8 @@ export type ProblemDetail = {
 };
 /** Normalized residual `{ error }` body. Unknown response fields are discarded. */
 export type SimpleErrorBody = {
+    /** The vector and variant routes' machine-readable code, when the body is `{ code, message }`. */
+    code?: string;
     error: string;
     issues?: SanitizedIssue[];
 };

package/errors.js

@@ -157,10 +157,23 @@ const normalizeProblem = (body, secrets) => {
     };
 };
 const normalizeSimple = (body, secrets) => {
-    if (!isRecord(body) || typeof body.error !== "string") {
+    if (!isRecord(body)) {
         return undefined;
     }
     const issues = sanitizeIssues(body.issues, secrets);
+    // `{ code, message }` is the vector routes' error body; keep its code.
+    if (typeof body.error !== "string" &&
+        typeof body.code === "string" &&
+        typeof body.message === "string") {
+        return {
+            code: safeString(body.code, secrets),
+            error: safeString(body.message, secrets),
+            ...(issues === undefined ? {} : { issues }),
+        };
+    }
+    if (typeof body.error !== "string") {
+        return undefined;
+    }
     return {
         error: safeString(body.error, secrets),
         ...(issues === undefined ? {} : { issues }),
@@ -211,7 +224,12 @@ export class MaterialGraphError extends Error {
         });
     }
     static fromTransport(input) {
-        if (input.callerSignal?.aborted === true) {
+        // A deadline (`AbortSignal.timeout`, or the client's `timeoutMs`) aborts
+        // the signal with a TimeoutError reason: that is a timeout, not a
+        // cancellation by the caller.
+        const reason = input.callerSignal?.reason;
+        const reasonName = reason instanceof Error ? reason.name : "";
+        if (input.callerSignal?.aborted === true && reasonName !== "TimeoutError") {
             return new MaterialGraphError("MaterialGraph request aborted by caller", {
                 ...requestMetadata(input),
                 kind: "aborted",
@@ -219,7 +237,7 @@ export class MaterialGraphError extends Error {
             });
         }
         const name = input.cause instanceof Error ? input.cause.name : "";
-        if (name === "TimeoutError") {
+        if (name === "TimeoutError" || reasonName === "TimeoutError") {
             return new MaterialGraphError("MaterialGraph request timed out", {
                 ...requestMetadata(input),
                 kind: "timeout",

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

@@ -106,6 +106,8 @@ export type ColorVariantMatch = {
     coverage: number;
     imageUrl: string | null;
     hex?: string | null;
+    /** True for a paint color card, paint line, primer or coating: the card is the brand's declared hex, never a photo. */
+    hasDeclaredColor: boolean;
     product: string;
     productId: string;
     variantId: string;

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

@@ -8,13 +8,13 @@ import type { PaintCatalogVariant } from "./find-variants-by-color-types.js";
  * are copied here and `contract-parity.test.ts` keeps them honest.
  */
 import type { ImageReferenceInput } from "./image-reference-types.js";
-import type { FilterGroups, ListVariantsItem } from "./list-variants-types.js";
+import type { FilterGroups, VariantCard } from "./list-variants-types.js";
 import type { SearchCatalogueSubset } from "./search-catalogue-subset-types.js";
 export declare const FIND_VARIANTS_BY_VECTOR_MODES: readonly ["text", "image", "text_and_image"];
 export type FindVariantsByVectorMode = (typeof FIND_VARIANTS_BY_VECTOR_MODES)[number];
 export type FindVariantsByVectorQuery = {
-    /** Exactly one reference. Only for image modes. */
-    image?: ImageReferenceInput;
+    /** One to six image references, each with exactly one field. Several are combined into one query, and every seed image's variant is left out. Only for image modes. Each image that has to be embedded spends one of the embed requests. */
+    images?: ImageReferenceInput[];
     mode: FindVariantsByVectorMode;
     /** Description, mood words included. Only for text modes. */
     text?: string;
@@ -31,7 +31,7 @@ export type FindVariantsByVectorInput = {
     /** Only this corpus scope. Absent or all: every variant. */
     searchCatalogueSubset?: SearchCatalogueSubset;
 };
-export type FindVariantsByVectorItem = Omit<ListVariantsItem, "materialBankId"> & {
+export type FindVariantsByVectorItem = Omit<VariantCard, "materialBankId"> & {
     /** The variant's Material Bank SKU; null means none is recorded. Always present here, unlike `list_variants`' optional field. */
     materialBankId: string | null;
     /** Voyage cosine to the query. Ranks only; not a probability. */
@@ -40,7 +40,7 @@ export type FindVariantsByVectorItem = Omit<ListVariantsItem, "materialBankId">
 export type FindVariantsByVectorReference = {
     id: string;
     kind: "url" | "assetId" | "variantId" | "sourceId";
-} | null;
+};
 export type FindVariantsByVectorScan = {
     /** True when no further candidates match; false means more may exist. */
     exhausted: boolean;
@@ -61,7 +61,8 @@ export type FindVariantsByVectorOutput = {
     excludedBySearchCatalogueSubset?: string[];
     items: FindVariantsByVectorItem[];
     mode: FindVariantsByVectorMode;
-    reference: FindVariantsByVectorReference;
+    /** The image references the query used, in order. Empty in text mode. */
+    references: FindVariantsByVectorReference[];
     /** The exact brand paint named by the text query, when held in the catalogue. */
     namedPaint?: PaintCatalogVariant;
     scan: FindVariantsByVectorScan;

package/get-variant-types.d.ts

@@ -52,6 +52,8 @@ export type GetVariantOutput = {
     sampleSubject: SampleSubject;
     /** The represented library color; null when none is established. */
     colorOptionValueId: string | null;
+    /** True for a paint color card, paint line, primer or coating: the card is the brand's declared hex, never a photo. */
+    hasDeclaredColor: boolean;
     code: string | null;
     /** Settled card color. Paint cards show this hex and have no photo. */
     hex?: string | null;

package/http-transport.d.ts

@@ -35,6 +35,8 @@ export type HttpTransportOptions = {
     apiKey: string;
     baseUrl: string;
     fetch: typeof fetch;
+    /** Deadline in milliseconds for each JSON or upload request. Not applied to streams. */
+    timeoutMs?: number;
 };
 export declare class HttpTransport {
     #private;

package/http-transport.js

@@ -32,11 +32,23 @@ export class HttpTransport {
     baseUrl;
     apiKey;
     fetch;
+    #timeoutMs;
     #lastRateLimit = null;
     constructor(options) {
         this.apiKey = options.apiKey;
         this.baseUrl = options.baseUrl.replace(/\/+$/u, "");
         this.fetch = options.fetch;
+        this.#timeoutMs = options.timeoutMs;
+    }
+    /** The caller's signal and the client deadline, whichever fires first. */
+    #withDeadline(signal) {
+        if (this.#timeoutMs === undefined) {
+            return signal;
+        }
+        const deadline = AbortSignal.timeout(this.#timeoutMs);
+        return signal === undefined
+            ? deadline
+            : AbortSignal.any([signal, deadline]);
     }
     get lastRateLimit() {
         return this.#lastRateLimit;
@@ -83,19 +95,21 @@ export class HttpTransport {
             origin: requestUrl.origin,
             path: requestUrl.pathname,
         };
+        // The deadline covers the whole request, body read included.
+        const signal = this.#withDeadline(input.signal);
         let response;
         try {
             response = await this.fetch(input.url, {
                 body: input.body,
                 headers: input.headers,
                 method: input.method,
-                signal: input.signal,
+                signal,
             });
         }
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                callerSignal: input.signal,
+                callerSignal: signal,
                 cause,
             });
         }
@@ -108,7 +122,7 @@ export class HttpTransport {
         catch (cause) {
             throw MaterialGraphError.fromTransport({
                 ...metadata,
-                callerSignal: input.signal,
+                callerSignal: signal,
                 cause,
             });
         }

package/index.d.ts

@@ -1,6 +1,6 @@
 export { MaterialGraphClient, DEFAULT_BASE_URL } from "./client.js";
 export type { MaterialGraphClientOptions } from "./client.js";
-export type { FilterOp, FilterTermCondition, FilterNumericCondition, FilterPresenceCondition, FilterAnyFieldCondition, FilterCondition, FilterGroups, OptionalFilterGroups, OrderByEntry, ListVariantsInclude, ListVariantsCollapse, ColorRegion, ColorRangeCondition, ListVariantsInput, ListVariantsPreference, ListVariantsSpecifications, ListVariantsNotApplicable, SampleSubject, ListVariantsItem, ListVariantsOutput, } from "./list-variants-types.js";
+export type { FilterOp, FilterTermCondition, FilterNumericCondition, FilterPresenceCondition, FilterAnyFieldCondition, FilterCondition, FilterGroups, OptionalFilterGroups, OrderByEntry, ListVariantsInclude, ListVariantsCollapse, ColorRegion, ColorRangeCondition, ListVariantsInput, ListVariantsPreference, ListVariantsSpecifications, ListVariantsNotApplicable, SampleSubject, ListVariantsItem, ListVariantsOutput, VariantCard, } from "./list-variants-types.js";
 export type { ListVariantFacetsInput, VariantFacetValue, CategoricalVariantFacet, BooleanVariantFacet, NumericVariantFacet, VariantFacet, ListVariantFacetsOutput, } from "./list-variant-facets-types.js";
 export type { SearchVariantsSelection, SearchVariantsInput, SearchVariantsUnderstood, SearchVariantsReading, SearchVariantsChoice, SearchVariantsOutput, } from "./search-variants-types.js";
 export type { ListEnumValuesOptions, EnumValueMatch, EnumValueItem, ListEnumValuesResult, } from "./list-enum-values-types.js";

package/list-variants-types.d.ts

@@ -190,6 +190,8 @@ export type ListVariantsItem = {
     sampleSubject: SampleSubject;
     /** The represented library color; null when none is established. */
     colorOptionValueId: string | null;
+    /** True for a paint color card, paint line, primer or coating: the card is the brand's declared hex, never a photo. */
+    hasDeclaredColor: boolean;
     code: string | null;
     /** Present only when `include` has `image`. */
     /** Settled card color. Paint cards show this hex and have no photo. */
@@ -220,6 +222,15 @@ export type ListVariantsItem = {
     variantCount?: number;
     variantId: string;
 };
+/**
+ * The variant card both `listVariants` rows and `findVariantsByVector` rows
+ * satisfy. The only difference between the two is the Material Bank SKU:
+ * absent in a list row when none is recorded, `null` in a vector row.
+ */
+export type VariantCard = Omit<ListVariantsItem, "materialBankId"> & {
+    /** The variant's Material Bank SKU. Absent or null means none is recorded. */
+    materialBankId?: string | null;
+};
 export type ListVariantsOutput = {
     /** Explicit `{field: "variant", op: "in"}` ids that name a real variant outside the materials catalogue. Present only when at least one did. */
     excludedBySearchCatalogueSubset?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "type": "module",
   "exports": {
     ".": {
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@materialinstruments/colorscope": "10.2.1"
+    "@materialinstruments/colorscope": "10.6.1"
   },
   "license": "Proprietary",
   "engines": {