@instruments/materialgraph 0.25.0 → 0.27.0

package/demand-batch-types.d.ts

@@ -18,35 +18,35 @@ import type { DemandMomentum, DemandQuarter, DemandSignal, OpenEnum } from "./ty
  * Body for `POST /api/v1/demand/batch` — enrich 1–48 already-selected candidate
  * ids with their real specification demand, in input order and cardinality.
  */
-export interface DemandBatchInput {
+export type DemandBatchInput = {
     /** 1–48 canonical variant ids. Order AND cardinality are preserved — duplicates are echoed, never collapsed. */
     variantIds: VariantId[];
     /** The behavioural signal to read demand from. Defaults to `sampled` (order co-occurrence) server-side. */
     signal?: DemandSignal;
     /** Optional declared context (e.g. `{ projectType: "hospitality" }`) — echoed for provenance, never used to rank or filter. */
     context?: Record<string, string>;
-}
+};
 /** Headline population behind the metric — this variant's own counts. */
-export interface DemandBatchPopulation {
+export type DemandBatchPopulation = {
     specCount: number;
     projectCount: number;
     customerCount: number;
-}
+};
 /** The consideration→specification funnel (project-grain; `exclusionRate` is annotate-only). */
-export interface DemandBatchFunnel {
+export type DemandBatchFunnel = {
     consideredProjects: number;
     specifiedProjects: number;
     excludedCount: number;
     exclusionRate: number;
-}
+};
 /** Per-result guardrail status — present on `internal` (`mg:admin`) results only. */
-export interface DemandBatchEvidence {
+export type DemandBatchEvidence = {
     belowPrivacyFloor: boolean;
     belowQualityFloor: boolean;
     suppressedForPublic: boolean;
-}
+};
 /** A variant that carries a usable demand signal. */
-export interface DemandBatchAvailableResult {
+export type DemandBatchAvailableResult = {
     variantId: VariantId;
     state: "available";
     population: DemandBatchPopulation;
@@ -57,28 +57,28 @@ export interface DemandBatchAvailableResult {
     funnel: DemandBatchFunnel | null;
     /** Exact guardrail evidence for `internal` callers; null for public. */
     evidence: DemandBatchEvidence | null;
-}
+};
 /**
  * A variant with a stats row that is below the public quality floor. We HAVE a
  * reading and are declining to publish it — not a claim that nobody specifies it.
  */
-export interface DemandBatchInsufficientResult {
+export type DemandBatchInsufficientResult = {
     variantId: VariantId;
     state: "insufficient_data";
-}
+};
 /**
  * A variant with no stats — indistinguishable from a privacy-suppressed one for
  * public callers, and therefore never reportable as "nobody specifies this".
  */
-export interface DemandBatchNoSignalResult {
+export type DemandBatchNoSignalResult = {
     variantId: VariantId;
     state: "no_signal";
-}
+};
 /** A requested id that resolves to no real variant. */
-export interface DemandBatchUnknownResult {
+export type DemandBatchUnknownResult = {
     variantId: VariantId;
     state: "unknown_variant";
-}
+};
 /**
  * One discriminated result per input id, in input order and cardinality.
  *
@@ -88,7 +88,7 @@ export interface DemandBatchUnknownResult {
  */
 export type DemandBatchResult = DemandBatchAvailableResult | DemandBatchInsufficientResult | DemandBatchNoSignalResult | DemandBatchUnknownResult;
 /** The `POST /api/v1/demand/batch` envelope. */
-export interface DemandBatchResponse {
+export type DemandBatchResponse = {
     /** The completed ingestion-session id these counts were mined in (the dataset generation). */
     generationId: string;
     metric: "specification_demand";
@@ -115,4 +115,4 @@ export interface DemandBatchResponse {
     /** The echoed declared context, or null when none was supplied. */
     context: Record<string, string> | null;
     results: DemandBatchResult[];
-}
+};

package/demand-types.d.ts

@@ -15,7 +15,7 @@
 import type { ProductId, VariantId } from "./identifiers.js";
 import type { CompanionDemand, DemandMomentum, DemandQuarter, OpenEnum } from "./types.js";
 /** A resolved seed material (identity block shared by the demand reads). */
-export interface DemandSeed {
+export type DemandSeed = {
     /** Opaque — round-trip verbatim. */
     variantId: VariantId;
     brand: string;
@@ -25,16 +25,16 @@ export interface DemandSeed {
     imageUrl: string | null;
     brandSlug: string;
     productId: ProductId;
-}
+};
 /** Headline demand stats for a seed: counts, quarterly series, momentum. */
-export interface MaterialDemandStats {
+export type MaterialDemandStats = {
     specCount: number;
     projectCount: number;
     customerCount: number;
     /** Sparse — a quarter with no activity is ABSENT, not a zero row. */
     byQuarter: DemandQuarter[];
     momentum: DemandMomentum;
-}
+};
 /**
  * `getMaterialDemand` result, passed through verbatim by the `/demand` route.
  *
@@ -42,14 +42,14 @@ export interface MaterialDemandStats {
  * the publication floor. It is never a reading of zero, and never licenses
  * "nobody specifies this".
  */
-export interface MaterialDemandResult {
+export type MaterialDemandResult = {
     found: boolean;
     query: string;
     seed: DemandSeed | null;
     /** The only window v1 serves. Activity outside it is unread, not absent. */
     window: "trailing_36mo";
     demand: MaterialDemandStats | null;
-}
+};
 /**
  * `getCoSpecifiedMaterials` result, passed through verbatim. The `companions`
  * list (materials specified alongside the seed) is included but left loosely
@@ -59,7 +59,7 @@ export interface MaterialDemandResult {
  * phrase matched several materials and `seedAlternatives` holds them — pick one
  * and re-ask by `variantId` rather than treating the first as the answer.
  */
-export interface CoSpecifiedResult {
+export type CoSpecifiedResult = {
     found: boolean;
     resolution: OpenEnum<"resolved" | "ambiguous" | "not_found">;
     query: string;
@@ -67,25 +67,25 @@ export interface CoSpecifiedResult {
     seedCategory: string | null;
     seedAlternatives: DemandSeed[];
     companions?: unknown[];
-}
+};
 /** The `/api/v1/demand` envelope — both domain reads side by side, verbatim. */
-export interface DemandResponse {
+export type DemandResponse = {
     query: string;
     demand: MaterialDemandResult;
     cospec: CoSpecifiedResult;
-}
+};
 /** Seed a demand read by EXACTLY ONE of `variantId` or `material`. */
-export interface DemandParams {
+export type DemandParams = {
     /** An exact variant id. Opaque — pass through verbatim. */
     variantId?: VariantId;
     /** Free text ("Brand Product Colour"), resolved server-side. May be ambiguous. */
     material?: string;
-}
-export interface CoordinateSeed extends DemandSeed {
+};
+export type CoordinateSeed = {
     /** The input reference this seed resolved from. */
     resolvedFrom: string;
-}
-export interface CoordinateCompanion {
+} & DemandSeed;
+export type CoordinateCompanion = {
     /** Opaque — round-trip verbatim. */
     variantId: VariantId;
     brand: string;
@@ -118,37 +118,37 @@ export interface CoordinateCompanion {
     totalLift: number;
     liftLabel: string;
     seedMatchCount: number;
-    seedContributions: Array<{
+    seedContributions: {
         seedVariantId: VariantId;
         lift: number;
-    }>;
+    }[];
     demand: CompanionDemand | null;
-    swatches: Array<{
+    swatches: {
         hex: string;
         proportion: number;
-    }>;
+    }[];
     /** Annotate-only appearance similarity — never reorders companions in v1. */
     colourFit: number | null;
-}
+};
 /**
  * The `POST /api/v1/pairings/coordinate` envelope. `unresolved` lists the input
  * references that matched nothing — read it before presenting `companions` as
  * "what goes with your palette", because a companion set derived from two of
  * four seeds is a different claim.
  */
-export interface CoordinateResponse {
+export type CoordinateResponse = {
     seeds: CoordinateSeed[];
     /** Input references that resolved to no material. Never silently dropped. */
     unresolved: string[];
     window: "trailing_36mo";
     companions: CoordinateCompanion[];
-}
+};
 /** Body for `POST /api/v1/pairings/coordinate`. */
-export interface CoordinateInput {
+export type CoordinateInput = {
     /** Free-text material references, resolved server-side; misses land in `unresolved`. */
     materials?: string[];
     /** Exact variant ids. Opaque — pass through verbatim. */
     variantIds?: VariantId[];
     projectType?: string;
     limit?: number;
-}
+};

package/errors.d.ts

@@ -2,9 +2,9 @@
 export type MaterialGraphErrorKind = "problem" | "simple" | "network" | "timeout" | "aborted" | "rate_limited" | "unexpected";
 export type SanitizedErrorValue = null | boolean | number | string | SanitizedErrorValue[] | SanitizedIssue;
 /** A bounded, recursively sanitized validation-issue record. */
-export interface SanitizedIssue {
+export type SanitizedIssue = {
     [key: string]: SanitizedErrorValue;
-}
+};
 /** Normalized RFC 7807 body. Unknown response fields are intentionally discarded. */
 export interface ProblemDetail {
     type: string;
@@ -25,22 +25,22 @@ export interface ProblemDetail {
     readonly [extension: string]: unknown;
 }
 /** Normalized residual `{ error }` body. Unknown response fields are discarded. */
-export interface SimpleErrorBody {
+export type SimpleErrorBody = {
     error: string;
     issues?: SanitizedIssue[];
-}
+};
 /** Parsed `X-RateLimit-*` / `Retry-After` headers. `null` means absent. */
-export interface RateLimit {
+export type RateLimit = {
     limit: number | null;
     remaining: number | null;
     reset: number | null;
     retryAfter: number | null;
-}
-export interface MaterialGraphRequestMetadata {
+};
+export type MaterialGraphRequestMetadata = {
     method: string;
     origin: string;
     path: string;
-}
+};
 export interface MaterialGraphErrorInit {
     kind: MaterialGraphErrorKind;
     status?: number;
@@ -55,18 +55,18 @@ export interface MaterialGraphErrorInit {
     /** Accepted for compatibility but deliberately never retained on the public error. */
     cause?: unknown;
 }
-interface ResponseErrorInput extends MaterialGraphRequestMetadata {
+type ResponseErrorInput = {
     status: number;
     body: unknown;
     responseText: string;
     rateLimit: RateLimit | null;
     apiKey: string;
     queryValues: readonly string[];
-}
-interface TransportErrorInput extends MaterialGraphRequestMetadata {
+} & MaterialGraphRequestMetadata;
+type TransportErrorInput = {
     cause: unknown;
     callerSignal?: AbortSignal;
-}
+} & MaterialGraphRequestMetadata;
 /**
  * MaterialGraph's documented problem EXTENSION members — the only non-standard
  * keys this client retains.
@@ -89,7 +89,7 @@ interface TransportErrorInput extends MaterialGraphRequestMetadata {
  * member to a problem response means adding it here too, and
  * `problem-extension-parity.test.ts` fails when the two disagree.
  */
-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", "unknown_attributes", "unknown_brands", "unknown_fields", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
+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", "unorderable_attribute", "valid_group_keys", "valid_type_keys"];
 /** The one error class thrown by all SDK transport and HTTP failures. */
 export declare class MaterialGraphError extends Error {
     readonly kind: MaterialGraphErrorKind;

package/errors.js

@@ -32,6 +32,7 @@ export const MATERIALGRAPH_PROBLEM_EXTENSIONS = [
     "missing_env",
     "orderable_attributes",
     "populated_alternatives",
+    "refused_criteria",
     "unknown_attributes",
     "unknown_brands",
     "unknown_fields",
@@ -43,38 +44,36 @@ const PROBLEM_EXTENSION_KEYS = new Set(MATERIALGRAPH_PROBLEM_EXTENSIONS);
 const MAX_UNEXPECTED_TEXT = 768;
 const MAX_EXTENSION_DEPTH = 8;
 const MAX_EXTENSION_ITEMS = 100;
-const MAX_EXTENSION_STRING = 1_024;
-function isRecord(value) {
-    return typeof value === "object" && value !== null;
-}
-function redact(text, secrets) {
-    return secrets.reduce((sanitized, secret) => {
-        if (secret.length === 0)
-            return sanitized;
-        return sanitized.split(secret).join("[REDACTED]");
-    }, text);
-}
-function safeString(text, secrets) {
-    return redact(text, secrets).slice(0, MAX_EXTENSION_STRING);
-}
-function secretVariants(apiKey, queryValues) {
-    return [
-        apiKey,
-        ...queryValues,
-        ...queryValues.map(encodeURIComponent),
-        ...queryValues.map((value) => new URLSearchParams([["value", value]]).toString().slice("value=".length)),
-    ];
-}
-function requestMetadata(input) {
-    return { method: input.method, origin: input.origin, path: input.path };
-}
+const MAX_EXTENSION_STRING = 1024;
+const isRecord = (value) => typeof value === "object" && value !== null;
+const redact = (text, secrets) => secrets.reduce((sanitized, secret) => {
+    if (secret.length === 0) {
+        return sanitized;
+    }
+    return sanitized.split(secret).join("[REDACTED]");
+}, text);
+const safeString = (text, secrets) => redact(text, secrets).slice(0, MAX_EXTENSION_STRING);
+const secretVariants = (apiKey, queryValues) => [
+    apiKey,
+    ...queryValues,
+    ...queryValues.map(encodeURIComponent),
+    ...queryValues.map((value) => new URLSearchParams([["value", value]]).toString().slice("value=".length)),
+];
+const requestMetadata = (input) => ({
+    method: input.method,
+    origin: input.origin,
+    path: input.path,
+});
 function sanitizeValue(value, secrets, depth = 0) {
-    if (depth >= MAX_EXTENSION_DEPTH)
+    if (depth >= MAX_EXTENSION_DEPTH) {
         return undefined;
-    if (value === null || typeof value === "boolean")
+    }
+    if (value === null || typeof value === "boolean") {
         return value;
-    if (typeof value === "number")
+    }
+    if (typeof value === "number") {
         return Number.isFinite(value) ? value : undefined;
+    }
     if (typeof value === "string") {
         return safeString(value, secrets);
     }
@@ -84,8 +83,9 @@ function sanitizeValue(value, secrets, depth = 0) {
             .map((item) => sanitizeValue(item, secrets, depth + 1))
             .filter((item) => item !== undefined);
     }
-    if (!isRecord(value))
+    if (!isRecord(value)) {
         return undefined;
+    }
     return sanitizeRecord(value, secrets, depth);
 }
 function sanitizeRecord(value, secrets, depth) {
@@ -99,15 +99,16 @@ function sanitizeRecord(value, secrets, depth) {
     });
     return Object.fromEntries(entries);
 }
-function sanitizeIssues(value, secrets) {
-    if (!Array.isArray(value))
+const sanitizeIssues = (value, secrets) => {
+    if (!Array.isArray(value)) {
         return undefined;
+    }
     return value
         .slice(0, MAX_EXTENSION_ITEMS)
         .filter((issue) => isRecord(issue) && !Array.isArray(issue))
         .map((issue) => sanitizeRecord(issue, secrets, 0));
-}
-function sanitizeSuggestions(value, secrets) {
+};
+const sanitizeSuggestions = (value, secrets) => {
     if (!Array.isArray(value) ||
         value.some((suggestion) => typeof suggestion !== "string")) {
         return undefined;
@@ -115,8 +116,8 @@ function sanitizeSuggestions(value, secrets) {
     return value
         .slice(0, MAX_EXTENSION_ITEMS)
         .map((suggestion) => safeString(suggestion, secrets));
-}
-function normalizeProblem(body, secrets) {
+};
+const normalizeProblem = (body, secrets) => {
     if (!isRecord(body) ||
         typeof body.type !== "string" ||
         typeof body.title !== "string" ||
@@ -150,24 +151,25 @@ function normalizeProblem(body, secrets) {
             : {}),
         ...(issues === undefined ? {} : { issues }),
     };
-}
-function normalizeSimple(body, secrets) {
-    if (!isRecord(body) || typeof body.error !== "string")
+};
+const normalizeSimple = (body, secrets) => {
+    if (!isRecord(body) || typeof body.error !== "string") {
         return undefined;
+    }
     const issues = sanitizeIssues(body.issues, secrets);
     return {
         error: safeString(body.error, secrets),
         ...(issues === undefined ? {} : { issues }),
     };
-}
-function unexpectedMessage(status, responseText, secrets) {
+};
+const unexpectedMessage = (status, responseText, secrets) => {
     const sanitized = redact(responseText, secrets)
         .trim()
         .slice(0, MAX_UNEXPECTED_TEXT);
     return sanitized.length > 0
         ? `MaterialGraph request failed with HTTP ${status}: ${sanitized}`
         : `MaterialGraph request failed with HTTP ${status}`;
-}
+};
 /** The one error class thrown by all SDK transport and HTTP failures. */
 export class MaterialGraphError extends Error {
     kind;
@@ -237,42 +239,42 @@ export class MaterialGraphError extends Error {
                 simple?.error ??
                 "MaterialGraph rate limit exceeded (429)", {
                 ...metadata,
-                status: input.status,
-                rateLimit: input.rateLimit,
                 kind: "rate_limited",
-                retriable: false,
-                traceId: problem?.trace_id,
                 problem,
+                rateLimit: input.rateLimit,
+                retriable: false,
                 simple,
+                status: input.status,
+                traceId: problem?.trace_id,
             });
         }
         if (problem !== undefined) {
             return new MaterialGraphError(problem.detail || problem.title, {
                 ...metadata,
-                status: input.status,
-                rateLimit: input.rateLimit,
                 kind: "problem",
+                problem,
+                rateLimit: input.rateLimit,
                 retriable: retriable || problem.is_retriable,
+                status: input.status,
                 traceId: problem.trace_id,
-                problem,
             });
         }
         if (simple !== undefined) {
             return new MaterialGraphError(simple.error, {
                 ...metadata,
-                status: input.status,
-                rateLimit: input.rateLimit,
                 kind: "simple",
+                rateLimit: input.rateLimit,
                 retriable,
                 simple,
+                status: input.status,
             });
         }
         return new MaterialGraphError(unexpectedMessage(input.status, input.responseText, secrets), {
             ...metadata,
             kind: "unexpected",
-            status: input.status,
-            retriable,
             rateLimit: input.rateLimit,
+            retriable,
+            status: input.status,
         });
     }
 }

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;