@instruments/materialgraph 0.25.0 → 0.26.0

package/coordinate-client.d.ts

@@ -7,7 +7,7 @@
  * limit, in the same per-lens shape as `brands-client` / `codes-client` /
  * `colours-client`. Behaviour is unchanged.
  */
-import { HttpTransport } from "./http-transport.js";
+import type { HttpTransport } from "./http-transport.js";
 import type { CoordinateInput, CoordinateResponse } from "./types.js";
 /**
  * THE QUESTION: "here is my whole scheme so far — what completes it?" The
@@ -20,4 +20,4 @@ import type { CoordinateInput, CoordinateResponse } from "./types.js";
  * scheme is COLOURS rather than materials. Check `unresolved` before presenting:
  * a reference that resolved to nothing is named there, not dropped.
  */
-export declare function coordinate(transport: HttpTransport, input: CoordinateInput, signal?: AbortSignal): Promise<CoordinateResponse>;
+export declare const coordinate: (transport: HttpTransport, input: CoordinateInput, signal?: AbortSignal) => Promise<CoordinateResponse>;

package/coordinate-client.js

@@ -1,13 +1,3 @@
-/**
- * The COORDINATION lens: given several materials already chosen, what completes
- * them. A thin wrapper over the shared {@link HttpTransport};
- * `MaterialGraphClient.coordinate` delegates here.
- *
- * Extracted from `client.ts`, which sits above the repository's source-size
- * limit, in the same per-lens shape as `brands-client` / `codes-client` /
- * `colours-client`. Behaviour is unchanged.
- */
-import { HttpTransport } from "./http-transport.js";
 import { resolveOperation } from "./operations.js";
 /**
  * THE QUESTION: "here is my whole scheme so far — what completes it?" The
@@ -20,6 +10,4 @@ import { resolveOperation } from "./operations.js";
  * scheme is COLOURS rather than materials. Check `unresolved` before presenting:
  * a reference that resolved to nothing is named there, not dropped.
  */
-export function coordinate(transport, input, signal) {
-    return transport.requestJson(resolveOperation("coordinate_materials"), { body: input, signal });
-}
+export const coordinate = async (transport, input, signal) => await transport.requestJson(resolveOperation("coordinate_materials"), { body: input, signal });

package/corpus-scope-types.d.ts

@@ -22,7 +22,7 @@
  * and this build does not, so a new scope is not a compile error in a client
  * that simply has not been republished yet.
  */
-import { type OpenEnum } from "./types.js";
+import type { OpenEnum } from "./types.js";
 /**
  * Every corpus a caller may ask for.
  *
@@ -50,8 +50,8 @@ export type CorpusScope = OpenEnum<"samplizeCatalogue" | "all" | "designShopOrde
  * the counts: a short page under a scope is a small SCOPED corpus, never a
  * truncated one.
  */
-export interface CorpusScopeReceipt {
+export type CorpusScopeReceipt = {
     scope: CorpusScope;
     /** What the scope admits, in one sentence, for a human reader. */
     description: string;
-}
+};

package/corpus-scope-types.js

@@ -1,25 +1 @@
-/**
- * The corpus scope vocabulary, declared ONCE for the whole client.
- *
- * ── Why this file exists ──
- * Until MG-1168 the union was spelled inline at six places across the SDK, and
- * five of them had gone stale: `designShopOrderable` shipped in MG-1144 and
- * reached only the search request type, so a TypeScript consumer could send the
- * scope to `/search` and not to `/browse` — against a server that had accepted
- * it on both since the day it landed. The narrowed RECEIPT types were worse
- * than the request ones, because a caller could not even name the scope it got
- * back.
- *
- * That is the third hop of the reachability checklist failing quietly: server
- * correct, published client unable to reach the surface. One alias means the
- * next member is one edit here rather than six edits nobody is reminded to
- * make. `corpus-scope-parity.test.ts` in `apps/web/config` fails if this file
- * falls behind `CORPUS_SCOPES`.
- *
- * ── Why `OpenEnum` ──
- * The server may add a scope before a consumer upgrades. `OpenEnum` keeps the
- * known members as autocomplete while still accepting a string the server knows
- * and this build does not, so a new scope is not a compile error in a client
- * that simply has not been republished yet.
- */
-import {} from "./types.js";
+export {};

package/correction-types.d.ts

@@ -27,20 +27,20 @@ export type CorrectionTarget = {
     url: string;
 };
 /** Caller-supplied evidence is not an independently verified graph reading. */
-export interface CorrectionEvidence {
+export type CorrectionEvidence = {
     state: "known" | "unknown" | "conflicting" | "not_applicable";
     value?: CorrectionJson;
     sourceUrl?: string;
     note?: string;
-}
-export interface CreateCorrectionInput {
+};
+export type CreateCorrectionInput = {
     target: CorrectionTarget;
     pageEvidence: CorrectionEvidence;
     graphEvidence: CorrectionEvidence;
     proposedChange: CorrectionJson;
     rationale: string;
-}
-export interface Correction {
+};
+export type Correction = {
     id: string;
     submission: CreateCorrectionInput;
     status: "submitted" | "in_review" | "resolved" | "withdrawn";
@@ -48,8 +48,8 @@ export interface Correction {
     createdAt: string;
     updatedAt: string;
     acceptedTruthChanged: false;
-}
-export interface CorrectionResponse {
+};
+export type CorrectionResponse = {
     data: Correction;
     meta: {
         operationId: "corrections.create";
@@ -65,8 +65,8 @@ export interface CorrectionResponse {
         self: string;
     };
     warnings: never[];
-}
-export interface CorrectionsListResponse {
+};
+export type CorrectionsListResponse = {
     data: Correction[];
     meta: {
         operationId: "corrections.list";
@@ -85,4 +85,4 @@ export interface CorrectionsListResponse {
         next: string | null;
     };
     warnings: never[];
-}
+};

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.

package/errors.js

@@ -43,38 +43,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 +82,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 +98,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 +115,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 +150,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 +238,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,
         });
     }
 }