@instruments/materialgraph 0.1.0 → 0.3.0

package/by-spec-types.d.ts

@@ -0,0 +1,73 @@
+export interface BySpecMatchedCell {
+    attributeId: string;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+/** The six states a verdict cell can report; open per the response-enum policy. */
+export type BySpecVerdictState = "matched" | "deviated" | "failed" | "unverified" | "missing" | "not_evaluated";
+/**
+ * One cell of a match's report card — how a single requested criterion scored.
+ * Hand-mirrors the `AttributeVerdict` contract from `@materialgraph/contracts`;
+ * the OpenAPI `CatalogBySpecResponse` schema is the source of truth on the wire.
+ */
+export interface BySpecVerdictCell {
+    attributeId: string;
+    state: BySpecVerdictState;
+    strength: "required" | "preferred";
+    baseline: {
+        kind: "term";
+        term: string;
+    } | {
+        kind: "presence";
+    } | {
+        kind: "seed";
+        variantId: string;
+    } | {
+        kind: "image";
+        source: "variant" | "vector";
+        variantId: string | null;
+    };
+    value: string | null;
+    deviation: {
+        direction: "above" | "below" | "other";
+        delta: number | null;
+        unit: string | null;
+        label: string;
+    } | null;
+    confidence: number | null;
+    sourceBasis: string | null;
+    trustGap: "below_confidence" | "basis_unmet" | "proposed" | null;
+}
+/** A match's full report card: every cell, the rolled-up grade, weakest confidence. */
+export interface BySpecVerdict {
+    cells: BySpecVerdictCell[];
+    grade: "meets_all" | "close" | "hard_no";
+    minConfidence: number | null;
+}
+/**
+ * The verdict a materials-search hit carries (MG-625). It IS the shared
+ * {@link BySpecVerdict} shape — the single CandidateVerdict mirror — aliased here
+ * so search-surface code can name it for what it is rather than duplicating it.
+ */
+export type MaterialVerdict = BySpecVerdict;
+export interface BySpecMatch {
+    variantId: string;
+    brand: string;
+    product: string;
+    variant: string;
+    color: string | null;
+    imageUrl: string | null;
+    hex: string | null;
+    matched: BySpecMatchedCell[];
+    minConfidence: number | null;
+    verdict: BySpecVerdict;
+}
+export interface BySpecResponse {
+    criteria: Array<{
+        attribute: string;
+        value: string;
+    }>;
+    totalMatches: number;
+    brandsSpanned: number;
+    matches: BySpecMatch[];
+}

package/by-spec-types.js

@@ -0,0 +1,7 @@
+// ── Catalog / spec — find-by-spec wire types ─────────────────────────────────
+//
+// Hand-maintained mirror of the `CatalogBySpecResponse` OpenAPI schema (the
+// source of truth on the wire); the `sdk-openapi-parity` test gates this against
+// the generated spec. Split out of `types.ts` to keep that file under its growth
+// baseline; re-exported from `types.ts` so importers see no change.
+export {};

package/client.d.ts

@@ -1,9 +1,17 @@
 import { type RateLimit } from "./errors.js";
+import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, ResumeRunOptions, RunEvent, SourceMaterialBatchDetail, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
+import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
+import type { MatchStreamEvent } from "./match-stream-types.js";
+import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
+import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.js";
+import { CodesClient } from "./codes-client.js";
+import { ColoursClient } from "./colours-client.js";
+import type { CodeAdvisoryInput, CodeAdvisoryResponse } from "./codes-types.js";
 import type { BrandCatalogListPage, BrandsOptions } from "./brand-types.js";
 import type { MaterialAssetProjection } from "./material-asset-types.js";
 import type { MaterialBlockProjection } from "./material-block-types.js";
 import type { SchemaResource, SchemaResourceResponse } from "./schema-resource-types.js";
-import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, ByColourParams, ByColourResponse, BrowseParams, BrowseResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, MatchInput, MatchResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, TaxonomyResponse, VocabularySearchOptions, VocabularySearchResponse, WhoamiResponse } from "./types.js";
+import type { ApplicableSpecsResponse, BrandOptions, BrandProfileResponse, ByColourParams, ByColourResponse, BrowseParams, BrowseResponse, BySpecOptions, BySpecResponse, ColourFacetsResponse, CoordinateInput, CoordinateResponse, DemandBatchInput, DemandBatchResponse, DemandParams, DemandResponse, ExtractPaletteInput, ExtractPaletteResponse, GlossaryTermResponse, MaterialResponse, MaterialsBatchDetailResponse, MaterialsBatchGetOptions, MaterialsBatchOptions, MaterialsBatchTileResponse, MatchInput, MatchResponse, PairingsOptions, PairingsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourResponse, SearchGetParams, SearchInput, SearchResponse, SiblingsResponse, SpecFacetsDistributionResponse, SpecFacetsListResponse, SuggestColourResponse, TaxonomyResponse, VocabularySearchOptions, VocabularySearchResponse, WhoamiResponse } from "./types.js";
 export declare const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
 export declare const MAX_BATCH_IDS = 100;
 export interface MaterialGraphClientOptions {
@@ -22,11 +30,57 @@ export declare class MaterialGraphClient {
     #private;
     readonly baseUrl: string;
     readonly browse: BrowseNamespace;
+    /**
+     * The advisory building-code surface: `codes.context()` to discover the
+     * vocabulary, `codes.requirements()` to state a space, `codes.advisory()` to
+     * badge candidates against it.
+     */
+    readonly codes: CodesClient;
+    /**
+     * The colour AGGREGATE surface: `colours.profiles()` for a category palette,
+     * `colours.stats()` for corpus colour coverage.
+     */
+    readonly colours: ColoursClient;
     constructor(options: MaterialGraphClientOptions);
     get lastRateLimit(): RateLimit | null;
+    /**
+     * The full search primitive (POST `/api/v1/search`). Layer a hard
+     * specification gate onto a ranked (colour / visual / lexical / seed) search
+     * via `input.filters` — each entry is a typed {@link SearchFilter} criterion:
+     * a term match (`{ attributeId, term }`), a presence check
+     * (`{ attributeId, hasValue: true }`), or a certification programme
+     * (`{ attributeId: "certification_programme", term }`). This is the seam for
+     * "a GREENGUARD-certified alternative to THIS material" (seed by `similarTo`,
+     * gate by `filters`) or "the same fire class, with an EPD on record". Build the
+     * filters with the `certificationProgramme` / `specTerm` / `hasSpec` helpers.
+     */
     search(input: SearchInput, signal?: AbortSignal): Promise<SearchResponse>;
     searchGet(params: SearchGetParams, signal?: AbortSignal): Promise<SearchResponse>;
     match(input: MatchInput, signal?: AbortSignal): Promise<MatchResponse>;
+    /**
+     * Material Match as a PROGRESSIVE stream — the same POST
+     * `/api/v1/search/match` endpoint negotiated with `Accept:
+     * application/x-ndjson`, which runs the scene workflow (classify → decompose →
+     * one match per surface) and emits an event as each surface resolves. Use this
+     * wherever the user watches a photo come apart; use {@link match} when you only
+     * want the finished answer.
+     *
+     * Iterate it directly — the request opens on the first `next()`:
+     *
+     * ```ts
+     * for await (const event of client.matchStream({ imageBase64 })) {
+     *   if (event.type === "surface") render(event.surface);
+     * }
+     * ```
+     *
+     * Every frame is validated before it is yielded, and the iterator ends only on
+     * a `complete` or `error` event — a truncated connection raises rather than
+     * passing for a short run. `signal` cancels the in-flight request itself, as
+     * does breaking out of the loop; a cancelled stream ends without raising.
+     * Requires an image (`imageBase64` or `imageUrl`); a `vector` input is
+     * buffered-only.
+     */
+    matchStream(input: MatchInput, signal?: AbortSignal): AsyncGenerator<MatchStreamEvent, void, unknown>;
     byColour(params: ByColourParams, signal?: AbortSignal): Promise<ByColourResponse>;
     /** Get a single material's detail record (GET `/api/v1/materials/{variantId}`). */
     material(variantId: string, options?: {
@@ -83,8 +137,15 @@ export declare class MaterialGraphClient {
     /** Search canonical attributes and value-dictionary terms together. */
     searchVocabulary(query: string, options?: VocabularySearchOptions, signal?: AbortSignal): Promise<VocabularySearchResponse>;
     /**
-     * Find materials by canonical specification (GET `/api/v1/search/specifications`).
-     * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL.
+     * Find materials by canonical specification across every brand — the
+     * value-anchored, spec-only primitive (GET `/api/v1/search/specifications`).
+     * Each `spec` is an `attribute:value` criterion; a variant must satisfy ALL of
+     * them, and each match carries per-criterion trust (`confidence` +
+     * `sourceBasis`). Answers "which materials, from anyone, are ASTM E84 Class A
+     * AND GREENGUARD-certified?" Build the strings with `specCriterion` /
+     * `certificationProgrammeCriterion` (e.g.
+     * `certificationProgrammeCriterion("GREENGUARD Gold")`); discover the queryable
+     * vocabulary with {@link specificationFacets} and {@link attributeValues}.
      */
     bySpec(spec: string | string[], options?: BySpecOptions, signal?: AbortSignal): Promise<BySpecResponse>;
     /** The product-category tree, flattened (GET `/api/v1/taxonomy/categories`). */
@@ -102,11 +163,55 @@ export declare class MaterialGraphClient {
      * `/api/v1/demand`). Provide EXACTLY ONE of `variantId` or `material`.
      */
     demand(params: DemandParams, signal?: AbortSignal): Promise<DemandResponse>;
+    /**
+     * Enrich a bounded set of ALREADY-CHOSEN candidate ids with their real
+     * specification demand (POST `/api/v1/demand/batch`, 1–48 ids). The bounded
+     * batch complement to {@link demand}: no fuzzy resolution, ranking, or
+     * reordering — each id yields one discriminated `state` (`available` /
+     * `insufficient_data` / `no_signal` / `unknown_variant`) in input order and
+     * cardinality. This is the Desk's "show demand momentum for every pick in this
+     * scheme" read; an `mg:admin` key additionally sees per-result `evidence`.
+     *
+     * @example
+     * // Rank a shortlist by real specification momentum before locking the scheme.
+     * const { results } = await mg.demandBatch({
+     *   variantIds: scheme.picks.map((p) => p.variantId),
+     *   signal: "sampled",
+     *   context: { projectType: "hospitality" },
+     * });
+     * const rising = results.filter(
+     *   (r) => r.state === "available" && r.momentum.state === "rising",
+     * );
+     */
+    demandBatch(input: DemandBatchInput, signal?: AbortSignal): Promise<DemandBatchResponse>;
+    /**
+     * Badge materials against the advisory building-code registry (POST
+     * `/api/v1/codes/advisory`). Identical to {@link CodesClient.advisory}, kept
+     * flat because it shipped before the `codes` namespace existed.
+     */
+    codeAdvisory(input: CodeAdvisoryInput, signal?: AbortSignal): Promise<CodeAdvisoryResponse>;
     /** Extract a named colour palette from an uploaded image (POST `/api/v1/search/palettes/extract`). */
     extractPalette(input: ExtractPaletteInput, signal?: AbortSignal): Promise<ExtractPaletteResponse>;
-    /** Discover the live specification-facet collection. */
+    /**
+     * Discover the live specification vocabulary (GET
+     * `/api/v1/catalog/specifications/facets`) — the facetable spec attributes that
+     * have real product-graph data, each with its top canonical values and the
+     * variants/brands behind them. This is where a caller LEARNS that the data
+     * exists: LEED, GREENGUARD, ASTM E84 Class A, FloorScore, EPDs all surface here
+     * with counts. Includes the virtual `certification_programme` facet (its values
+     * are programme names). Learn an `attribute:value` here, then reuse it as a
+     * {@link bySpec} criterion or a {@link search} `filters` entry. NOTE: continuous
+     * numeric specs (e.g. `slip_resistance_dcof`, a 0–1 DCOF range) are NOT
+     * token-facetable and do not appear here — read those per-attribute.
+     */
     specificationFacets(signal?: AbortSignal): Promise<SpecFacetsListResponse>;
-    /** List the live values for one canonical attribute. */
+    /**
+     * List the live value distribution for ONE canonical attribute (GET
+     * `/api/v1/catalog/attributes/{attributeId}/values`), ordered by cross-brand
+     * reach with variant + brand counts. The drill-in companion to
+     * {@link specificationFacets} — e.g. every certification programme on record,
+     * or every fire classification and how many variants carry each.
+     */
     attributeValues(attributeId: string, signal?: AbortSignal): Promise<SpecFacetsDistributionResponse>;
     /** The specs a product type COULD carry (GET `/api/v1/taxonomy/categories/{key}/specs`). */
     applicableSpecs(key: string, signal?: AbortSignal): Promise<ApplicableSpecsResponse>;
@@ -114,6 +219,80 @@ export declare class MaterialGraphClient {
     glossary(term: string, signal?: AbortSignal): Promise<GlossaryTermResponse>;
     /** List registered brands (GET `/api/v1/brands`). */
     brands(options?: BrandsOptions, signal?: AbortSignal): Promise<BrandCatalogListPage>;
-    /** Resolve a brand and return its profile + trade signals (GET `/api/v1/brands/{slug}`). */
-    brand(slug: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
+    /** Resolve a brand and return its profile + trade signals (GET `/api/v1/brands/{brandSlug}`). */
+    brand(brandSlug: string, options?: BrandOptions, signal?: AbortSignal): Promise<BrandProfileResponse>;
+    /**
+     * Upload one atomic source-material batch (POST `/api/v1/source-material`,
+     * multipart). Pass a heterogeneous pile via `{ files }` (any mix of PDF,
+     * text/markdown, and images — the server classifies each) or the legacy
+     * `{ brief, references }` shape. Requires the `mg:ingest` scope.
+     */
+    uploadSourceMaterial(input: UploadSourceMaterialInput, signal?: AbortSignal): Promise<SourceMaterialBatchReceipt>;
+    /**
+     * Read back an uploaded batch (GET `/api/v1/source-material/{batchId}`): every
+     * file with a fetchable `url` and its analyses inlined. `analyses` is always
+     * an array — `[]` means nothing has been computed yet. Analyses are shared by
+     * content hash, so re-uploading an already-analysed image returns its analysis
+     * immediately. A batch you do not own raises the same 404 as one that does not
+     * exist. Requires the `mg:compose` scope.
+     */
+    sourceMaterialBatch(batchId: string, signal?: AbortSignal): Promise<SourceMaterialBatchDetail>;
+    /** List invocable agents, workflows, and tools (GET `/api/v1/capabilities`). */
+    capabilities(signal?: AbortSignal): Promise<CapabilityManifestResponse>;
+    /** Start an asynchronous capability Run (POST `/api/v1/runs`). */
+    createRun(body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
+    /** Get a Run's current state (GET `/api/v1/runs/{runId}`). */
+    run(runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
+    /**
+     * Export a completed compose Run's scheme as a finish schedule — one row per
+     * slot, every attribute value carrying its source and verification state
+     * (GET `/api/v1/runs/{runId}/schedule`). Unknown values are explicit
+     * `missing` cells, never blanks. The `.xlsx` form is a direct-URL download:
+     * `GET /api/v1/runs/{runId}/schedule.xlsx` with the same bearer key.
+     */
+    runSchedule(runId: string, options?: GetRunScheduleOptions): Promise<FinishScheduleResponse>;
+    /**
+     * Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`).
+     *
+     * The third argument accepts either an `AbortSignal` (the published form) or
+     * {@link ResumeRunOptions}, whose `stepId` guards against resuming a step the
+     * run has already moved past — the API answers 409 on a mismatch (MG-608).
+     */
+    resumeRun(runId: string, resumeData: unknown, signalOrOptions?: AbortSignal | ResumeRunOptions): Promise<PublicRunResponse>;
+    /** Request durable Run cancellation (POST `/api/v1/runs/{runId}/cancel`). */
+    cancelRun(runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
+    /**
+     * Derive an "option B" scheme from a succeeded compose Run along one
+     * constraint axis (POST `/api/v1/schemes/vary`). Deterministic and
+     * synchronous — the response IS the hydrated scheme (no Run envelope), stamped
+     * with axis + source provenance whose `notes` are the variation's receipts.
+     * Requires the `mg:read` scope.
+     */
+    varyScheme(body: VarySchemesRequest, signal?: AbortSignal): Promise<VarySchemesResponse>;
+    /**
+     * Stream ordered Run events as an async iterator (GET
+     * `/api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or the
+     * signal aborts; pass `after` to resume from the last observed sequence.
+     */
+    streamRunEvents(runId: string, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent>;
+    /**
+     * Create a persistent project owned by the caller (POST `/api/v1/projects`).
+     * Returns the freshly assembled state (an empty event log). Requires the
+     * `mg:ingest` scope.
+     */
+    createProject(body?: CreateProjectRequest, signal?: AbortSignal): Promise<ProjectState>;
+    /** Read a project's assembled state (GET `/api/v1/projects/{projectId}`). */
+    getProject(projectId: string, signal?: AbortSignal): Promise<ProjectState>;
+    /**
+     * Append one event to a project's append-only process trail (POST
+     * `/api/v1/projects/{projectId}/events`). Requires the `mg:ingest` scope.
+     */
+    appendProjectEvent(projectId: string, body: AppendProjectEventRequest, signal?: AbortSignal): Promise<ProjectEventReceipt>;
+    /** List the caller's own projects, newest first (GET `/api/v1/projects`). */
+    listProjects(signal?: AbortSignal): Promise<ProjectListResponse>;
+    /**
+     * Collect Run events until a terminal event, the deadline, or the stream ends
+     * — the bounded events-log pattern (a single pass over {@link streamRunEvents}).
+     */
+    drainRunEvents(runId: string, options: DrainRunEventsOptions): Promise<RunEvent[]>;
 }