@instruments/materialgraph 0.1.0 → 0.2.0

package/client.d.ts

@@ -1,9 +1,13 @@
 import { type RateLimit } from "./errors.js";
+import type { CapabilityManifestResponse, CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, RunEvent, SourceMaterialBatchReceipt, StreamRunEventsOptions, UploadSourceMaterialInput } from "./run-types.js";
+import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
+import type { VarySchemesRequest, VarySchemesResponse } from "./composition-types.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 {
@@ -24,6 +28,17 @@ export declare class MaterialGraphClient {
     readonly browse: BrowseNamespace;
     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>;
@@ -83,8 +98,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 +124,72 @@ 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 a set of materials against the advisory building-code registry for one
+     * (jurisdiction, occupancy, space, sprinklered) context (POST
+     * `/api/v1/codes/advisory`, ≤ 48 ids). Every applicable requirement is badged
+     * `meets` / `shortfall` / `unknown` from the material's accepted fire and
+     * slip-resistance facts, in input order. ADVISORY ONLY — every verdict and the
+     * envelope carry the AHJ caveat; this is model code as adopted, never a legal
+     * determination.
+     *
+     * @example
+     * // Badge this scheme's picks for a Texas hospitality fire-code review.
+     * const advisory = await mg.codeAdvisory({
+     *   variantIds: scheme.picks.map((p) => p.variantId),
+     *   jurisdictionId: "us-tx",
+     *   occupancyGroup: "A-2", // assembly — restaurant / bar
+     *   spaceType: "corridor",
+     *   sprinklered: true,
+     * });
+     * const shortfalls = advisory.results.filter((r) =>
+     *   r.requirements.some((req) => req.verdict === "shortfall"),
+     * );
+     */
+    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 +197,57 @@ 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>;
+    /** 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>;
+    /** Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`). */
+    resumeRun(runId: string, resumeData: unknown, signal?: AbortSignal): 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[]>;
 }

package/client.js

@@ -1,5 +1,8 @@
 import { MaterialGraphError } from "./errors.js";
-import { SDK_OPERATIONS } from "./operations.js";
+import { HttpTransport } from "./http-transport.js";
+import { findSdkOperation } from "./operations.js";
+import { cancelRun, capabilities as capabilitiesRun, createRun, drainRunEvents, getRun, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
 export const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
 export const MAX_BATCH_IDS = 100;
 const SCHEMA_RESOURCE_OPERATION_IDS = {
@@ -14,145 +17,50 @@ const SCHEMA_RESOURCE_OPERATION_IDS = {
     mappings: "list_schema_mappings",
 };
 function operation(operationId) {
-    const match = SDK_OPERATIONS.find((candidate) => candidate.operationId === operationId);
+    const match = findSdkOperation(operationId);
     if (!match) {
         throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
     }
     return match;
 }
-function operationPath(sdkOperation, pathParams = {}) {
-    return Object.entries(pathParams).reduce((path, [name, value]) => path.replace(`{${name}}`, encodeURIComponent(value)), sdkOperation.path);
-}
-function parseIntOrNull(value) {
-    if (value === null)
-        return null;
-    const n = Number.parseInt(value, 10);
-    return Number.isNaN(n) ? null : n;
-}
-function 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"));
-    const retryAfter = parseIntOrNull(headers.get("retry-after"));
-    if (limit === null && remaining === null && reset === null && retryAfter === null) {
-        return null;
-    }
-    return { limit, remaining, reset, retryAfter };
-}
 export class MaterialGraphClient {
     baseUrl;
     browse;
-    #apiKey;
-    #fetch;
-    #lastRateLimit = null;
+    #transport;
     constructor(options) {
         if (!options.apiKey) {
             throw MaterialGraphError.unexpected("MaterialGraphClient: `apiKey` is required.");
         }
-        this.#apiKey = options.apiKey;
-        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-        this.#fetch = options.fetch ?? globalThis.fetch;
+        this.#transport = new HttpTransport({
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            fetch: options.fetch ?? globalThis.fetch,
+        });
+        this.baseUrl = this.#transport.baseUrl;
         const browse = (params, signal) => this.#browsePage(params, signal);
         browse.pages = (params, signal) => this.#browsePages(params, signal);
         this.browse = browse;
     }
     get lastRateLimit() {
-        return this.#lastRateLimit;
-    }
-    #buildUrl(path, query) {
-        const url = new URL(`${this.baseUrl}${path}`);
-        if (query) {
-            for (const [key, value] of Object.entries(query)) {
-                if (value === undefined || value === null)
-                    continue;
-                if (Array.isArray(value)) {
-                    for (const item of value) {
-                        if (item !== undefined && item !== null) {
-                            url.searchParams.append(key, String(item));
-                        }
-                    }
-                }
-                else {
-                    url.searchParams.append(key, String(value));
-                }
-            }
-        }
-        return url.toString();
-    }
-    async #request(sdkOperation, options = {}) {
-        const path = operationPath(sdkOperation, options.pathParams);
-        const url = this.#buildUrl(path, options.query);
-        const requestUrl = new URL(url);
-        const requestMetadata = {
-            method: sdkOperation.method,
-            origin: requestUrl.origin,
-            path: requestUrl.pathname,
-        };
-        const headers = {
-            Authorization: `Bearer ${this.#apiKey}`,
-            Accept: "application/json",
-        };
-        const hasBody = options.body !== undefined;
-        if (hasBody)
-            headers["Content-Type"] = "application/json";
-        let response;
-        try {
-            response = await this.#fetch(url, {
-                method: sdkOperation.method,
-                headers,
-                body: hasBody ? JSON.stringify(options.body) : undefined,
-                signal: options.signal,
-            });
-        }
-        catch (cause) {
-            throw MaterialGraphError.fromTransport({
-                ...requestMetadata,
-                cause,
-                callerSignal: options.signal,
-            });
-        }
-        const rateLimit = parseRateLimit(response.headers);
-        this.#lastRateLimit = rateLimit;
-        let text;
-        try {
-            text = await response.text();
-        }
-        catch (cause) {
-            throw MaterialGraphError.fromTransport({
-                ...requestMetadata,
-                cause,
-                callerSignal: options.signal,
-            });
-        }
-        let parsed;
-        if (text.length > 0) {
-            try {
-                parsed = JSON.parse(text);
-            }
-            catch {
-                parsed = text;
-            }
-        }
-        if (!response.ok) {
-            const querySecrets = [...requestUrl.searchParams.values()];
-            throw MaterialGraphError.fromResponse({
-                ...requestMetadata,
-                status: response.status,
-                body: parsed,
-                responseText: text,
-                rateLimit,
-                apiKey: this.#apiKey,
-                queryValues: querySecrets,
-            });
-        }
-        return parsed;
+        return this.#transport.lastRateLimit;
     }
     #get(operationId, query, signal, pathParams) {
-        return this.#request(operation(operationId), { query, signal, pathParams });
+        return this.#transport.requestJson(operation(operationId), { query, signal, pathParams });
     }
     #post(operationId, body, signal) {
-        return this.#request(operation(operationId), { body, signal });
+        return this.#transport.requestJson(operation(operationId), { body, signal });
     }
+    /**
+     * 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, signal) {
         return this.#post("search_materials_post", input, signal);
     }
@@ -264,8 +172,15 @@ export class MaterialGraphClient {
         return this.#get("catalog_vocabulary_search", { q: query, limit: options?.limit, kind: options?.kind }, signal);
     }
     /**
-     * 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, options, signal) {
         return this.#get("catalog_by_spec", { spec: Array.isArray(spec) ? spec : [spec], limit: options?.limit }, signal);
@@ -295,17 +210,83 @@ export class MaterialGraphClient {
     demand(params, signal) {
         return this.#get("get_material_demand", { variantId: params.variantId, material: params.material }, signal);
     }
+    /**
+     * 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, signal) {
+        return this.#post("get_demand_batch", input, signal);
+    }
+    // ── Codes (advisory building-code compliance) ────────────────────────────────
+    /**
+     * Badge a set of materials against the advisory building-code registry for one
+     * (jurisdiction, occupancy, space, sprinklered) context (POST
+     * `/api/v1/codes/advisory`, ≤ 48 ids). Every applicable requirement is badged
+     * `meets` / `shortfall` / `unknown` from the material's accepted fire and
+     * slip-resistance facts, in input order. ADVISORY ONLY — every verdict and the
+     * envelope carry the AHJ caveat; this is model code as adopted, never a legal
+     * determination.
+     *
+     * @example
+     * // Badge this scheme's picks for a Texas hospitality fire-code review.
+     * const advisory = await mg.codeAdvisory({
+     *   variantIds: scheme.picks.map((p) => p.variantId),
+     *   jurisdictionId: "us-tx",
+     *   occupancyGroup: "A-2", // assembly — restaurant / bar
+     *   spaceType: "corridor",
+     *   sprinklered: true,
+     * });
+     * const shortfalls = advisory.results.filter((r) =>
+     *   r.requirements.some((req) => req.verdict === "shortfall"),
+     * );
+     */
+    codeAdvisory(input, signal) {
+        return this.#post("resolveCodeAdvisory", input, signal);
+    }
     // ── Colour helpers (extract) ─────────────────────────────────────────────────
     /** Extract a named colour palette from an uploaded image (POST `/api/v1/search/palettes/extract`). */
     extractPalette(input, signal) {
         return this.#post("extract_image_palette", input, signal);
     }
     // ── Catalog (facets / applicable specs / glossary) ───────────────────────────
-    /** 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) {
         return this.#get("list_spec_facets", undefined, signal);
     }
-    /** 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, signal) {
         return this.#get("list_attribute_values", undefined, signal, {
             attributeId,
@@ -324,10 +305,89 @@ export class MaterialGraphClient {
     brands(options = {}, signal) {
         return this.#get("list_brands", { q: options.q, limit: options.limit, offset: options.offset }, signal);
     }
-    /** Resolve a brand and return its profile + trade signals (GET `/api/v1/brands/{slug}`). */
-    brand(slug, options, signal) {
+    /** Resolve a brand and return its profile + trade signals (GET `/api/v1/brands/{brandSlug}`). */
+    brand(brandSlug, options, signal) {
         return this.#get("get_brand_profile", { q: options?.q }, signal, {
-            slug,
+            brandSlug,
         });
     }
+    // ── Runs (the hosted agentic surface) ────────────────────────────────────────
+    /**
+     * 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, signal) {
+        return uploadSourceMaterial(this.#transport, input, signal);
+    }
+    /** List invocable agents, workflows, and tools (GET `/api/v1/capabilities`). */
+    capabilities(signal) {
+        return capabilitiesRun(this.#transport, signal);
+    }
+    /** Start an asynchronous capability Run (POST `/api/v1/runs`). */
+    createRun(body, signal) {
+        return createRun(this.#transport, body, signal);
+    }
+    /** Get a Run's current state (GET `/api/v1/runs/{runId}`). */
+    run(runId, signal) {
+        return getRun(this.#transport, runId, signal);
+    }
+    /** Resume a suspended Run (POST `/api/v1/runs/{runId}/resume`). */
+    resumeRun(runId, resumeData, signal) {
+        return resumeRun(this.#transport, runId, resumeData, signal);
+    }
+    /** Request durable Run cancellation (POST `/api/v1/runs/{runId}/cancel`). */
+    cancelRun(runId, signal) {
+        return cancelRun(this.#transport, runId, signal);
+    }
+    /**
+     * 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, signal) {
+        return this.#post("vary_schemes", body, signal);
+    }
+    /**
+     * 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, options) {
+        return streamRunEvents(this.#transport, runId, options);
+    }
+    // ── Projects (the persistent Material Box entity) ────────────────────────────
+    /**
+     * 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 = {}, signal) {
+        return createProjectCall(this.#transport, body, signal);
+    }
+    /** Read a project's assembled state (GET `/api/v1/projects/{projectId}`). */
+    getProject(projectId, signal) {
+        return getProjectCall(this.#transport, projectId, signal);
+    }
+    /**
+     * Append one event to a project's append-only process trail (POST
+     * `/api/v1/projects/{projectId}/events`). Requires the `mg:ingest` scope.
+     */
+    appendProjectEvent(projectId, body, signal) {
+        return appendProjectEventCall(this.#transport, projectId, body, signal);
+    }
+    /** List the caller's own projects, newest first (GET `/api/v1/projects`). */
+    listProjects(signal) {
+        return listProjectsCall(this.#transport, signal);
+    }
+    /**
+     * 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, options) {
+        return drainRunEvents(this.#transport, runId, options);
+    }
 }

package/codes-types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Hand-mirrored wire types for the advisory building-code surface
+ * (`POST /api/v1/codes/advisory`, MG-433).
+ *
+ * Like the rest of the SDK these interfaces have NO runtime dependency on any
+ * `@materialgraph/*` package — they mirror the `codeAdvisoryInputSchema` /
+ * `codeAdvisoryResultSchema` Zod contracts the route is built from. Response
+ * enums follow the SDK's TOLERANT-PARSING contract (widened with `OpenEnum` so a
+ * new server value still type-checks); `requirement.scale` is an open IBC-scale
+ * id and `caveat` is the AHJ advisory sentence, both read as plain strings.
+ *
+ * ADVISORY ONLY: every verdict and the envelope carry the AHJ caveat — this is
+ * model code as adopted, never a legal determination.
+ */
+import type { OpenEnum } from "./types.js";
+/**
+ * Badge a bounded set of materials against the code-requirement registry for one
+ * (jurisdiction, occupancy, space, sprinklered) context. `results` preserve
+ * input order and cardinality (duplicate ids are echoed).
+ */
+export interface CodeAdvisoryInput {
+    /** 1–48 opaque variant ids to badge, echoed back in `results` in this exact order. */
+    variantIds: string[];
+    /** A seeded jurisdiction id (e.g. `"us-tx"`); an unknown id is a 400. */
+    jurisdictionId: string;
+    /** The IBC occupancy group for the space (e.g. `"I-2"` hospital, `"A-2"` restaurant). */
+    occupancyGroup: string;
+    /** The finish-location / space type (e.g. `"corridor"`, `"exit_enclosure"`). */
+    spaceType: string;
+    /** Whether the space is sprinklered — relaxes several fire-finish floors. */
+    sprinklered: boolean;
+}
+/** The resolved jurisdiction the verdicts were evaluated against. */
+export interface CodeAdvisoryJurisdiction {
+    id: string;
+    name: string;
+    codeFamily: string;
+    edition: string;
+    adoptionNote: string;
+}
+/** The echoed evaluation context (the space the badges apply to). */
+export interface CodeAdvisoryContext {
+    occupancyGroup: string;
+    spaceType: string;
+    sprinklered: boolean;
+}
+/** The threshold one requirement imposes: a class floor and/or a numeric floor. */
+export interface CodeRequirementThreshold {
+    /** The IBC classification scale this requirement is measured on (open id). */
+    scale: string;
+    /** The minimum acceptable class on `scale`, or null when only a numeric floor applies. */
+    minClass: string | null;
+    /** A numeric floor (e.g. a DCOF minimum), or null when only a class floor applies. */
+    numericFloor: {
+        metric: string;
+        value: number;
+        unit: string;
+    } | null;
+}
+/** The accepted fact a verdict was decided from (null when the material carried none). */
+export interface CodeRequirementEvidence {
+    attributeId: OpenEnum<"fire_classifications" | "slip_resistance_dcof">;
+    value: string;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+/** One requirement badged against one material. */
+export interface CodeRequirementVerdict {
+    requirementId: string;
+    dimension: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
+    section: string;
+    requirement: CodeRequirementThreshold;
+    /** `meets` / `shortfall` / `unknown` — `unknown` when no defensible fact maps onto `scale`. */
+    verdict: OpenEnum<"meets" | "shortfall" | "unknown">;
+    evidence: CodeRequirementEvidence | null;
+    /** The AHJ advisory caveat — model code as adopted, never a legal determination. */
+    caveat: string;
+}
+/** Per-variant advisory outcome, in input order. */
+export interface CodeAdvisoryVariantResult {
+    variantId: string;
+    /** `evaluated` when the id resolved; `unknown_variant` (with `requirements: []`) when it did not. */
+    state: OpenEnum<"evaluated" | "unknown_variant">;
+    requirements: CodeRequirementVerdict[];
+}
+/** The `POST /api/v1/codes/advisory` envelope — per-variant, per-requirement verdicts. */
+export interface CodeAdvisoryResponse {
+    jurisdiction: CodeAdvisoryJurisdiction;
+    context: CodeAdvisoryContext;
+    /** The AHJ advisory caveat, at the envelope level too. */
+    caveat: string;
+    results: CodeAdvisoryVariantResult[];
+}

package/codes-types.js

@@ -0,0 +1 @@
+export {};