@instruments/materialgraph 0.1.0 → 0.3.0

package/client.js

@@ -1,5 +1,11 @@
 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, getRunSchedule, getSourceMaterialBatch as getSourceMaterialBatchCall, resumeRun, streamRunEvents, uploadSourceMaterial, } from "./runs.js";
+import { matchStream as matchStreamCall } from "./match-stream.js";
+import { appendProjectEvent as appendProjectEventCall, createProject as createProjectCall, getProject as getProjectCall, listProjects as listProjectsCall, } from "./projects.js";
+import { CodesClient } from "./codes-client.js";
+import { ColoursClient } from "./colours-client.js";
 export const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
 export const MAX_BATCH_IDS = 100;
 const SCHEMA_RESOURCE_OPERATION_IDS = {
@@ -14,145 +20,68 @@ 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;
+    /**
+     * The advisory building-code surface: `codes.context()` to discover the
+     * vocabulary, `codes.requirements()` to state a space, `codes.advisory()` to
+     * badge candidates against it.
+     */
+    codes;
+    /**
+     * The colour AGGREGATE surface: `colours.profiles()` for a category palette,
+     * `colours.stats()` for corpus colour coverage.
+     */
+    colours;
+    #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;
+        this.codes = new CodesClient({
+            get: (operationId, query, signal) => this.#get(operationId, query, signal),
+            post: (operationId, body, signal) => this.#post(operationId, body, signal),
+        });
+        this.colours = new ColoursClient({
+            get: (operationId, query, signal) => this.#get(operationId, query, signal),
+        });
     }
     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);
     }
@@ -162,6 +91,32 @@ export class MaterialGraphClient {
     match(input, signal) {
         return this.#post("match_material", input, signal);
     }
+    /**
+     * 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, signal) {
+        return matchStreamCall(this.#transport, input, signal);
+    }
     byColour(params, signal) {
         return this.#get("search_by_colour", {
             hex: params.hex,
@@ -264,8 +219,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 +257,66 @@ 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 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, signal) {
+        return this.codes.advisory(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 +335,116 @@ 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);
+    }
+    /**
+     * 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, signal) {
+        return getSourceMaterialBatchCall(this.#transport, batchId, 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);
+    }
+    /**
+     * 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, options) {
+        return getRunSchedule(this.#transport, runId, options);
+    }
+    /**
+     * 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, resumeData, signalOrOptions) {
+        return resumeRun(this.#transport, runId, resumeData, signalOrOptions);
+    }
+    /** 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-client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The advisory building-code surface, namespaced as `mg.codes`.
+ *
+ * Three calls that are one workflow — discover the vocabulary, state the space,
+ * then badge candidates against it — so they live together rather than as three
+ * flat methods on an already-large client facade. `mg.browse` set the precedent
+ * for a namespace when a capability is a small family rather than a single verb.
+ *
+ * The namespace holds no transport of its own: the client hands it bound
+ * `get`/`post` callbacks, so auth, rate-limit accounting and error shaping stay
+ * in exactly one place.
+ *
+ * ADVISORY ONLY: every verdict and every envelope carries the AHJ caveat — this
+ * is model code as adopted, never a legal determination.
+ */
+import type { CodeAdvisoryInput, CodeAdvisoryResponse, CodeContextRequest, CodeContextResponse, CodeRequirementsResponse } from "./codes-types.js";
+import type { QueryParams } from "./http-transport.js";
+import type { SdkOperationId } from "./operations.js";
+/** The client's own request primitives, handed down so this file owns no transport. */
+export interface CodesTransport {
+    get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal): Promise<T>;
+    post<T>(operationId: SdkOperationId, body: unknown, signal?: AbortSignal): Promise<T>;
+}
+export declare class CodesClient {
+    #private;
+    constructor(transport: CodesTransport);
+    /**
+     * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
+     * seeded jurisdictions and their coverage tier, the occupancy groups the
+     * registry keys on, finish locations, dimensions, classification scales with
+     * classes ordered best-first, and which `ms_room` term correlates to which
+     * regulatory axes.
+     *
+     * Start here — every value the other two calls accept is listed in this one
+     * response, so nothing need be hardcoded. A correlation the registry refuses to
+     * make comes back `null`, never a guess.
+     *
+     * @example
+     * const vocab = await mg.codes.context();
+     * const texas = vocab.jurisdictions.find((j) => j.id === "us-tx");
+     * // `model_baseline` means unamended model IBC stood in for this AHJ's own table.
+     * console.log(texas?.coverage, texas?.adoptionNote);
+     */
+    context(signal?: AbortSignal): Promise<CodeContextResponse>;
+    /**
+     * What a space demands, before any candidate exists (GET
+     * `/api/v1/codes/requirements`). State the space by explicit axes, or by a
+     * `roomType` the axes are correlated from.
+     *
+     * An empty `requirements` array means nothing in the registry applies to this
+     * context. It is NOT a pass.
+     *
+     * @example
+     * const { requirements } = await mg.codes.requirements({
+     *   jurisdictionId: "us-tx",
+     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
+     *   spaceType: "corridors",
+     *   sprinklered: true,
+     * });
+     * requirements.map((r) => `${r.dimension}: ${r.label} (${r.section})`);
+     */
+    requirements(input: CodeContextRequest, signal?: AbortSignal): Promise<CodeRequirementsResponse>;
+    /**
+     * Badge materials against the advisory building-code registry for one context
+     * (POST `/api/v1/codes/advisory`, ≤ 100 ids). Each applicable requirement is
+     * badged `meets` / `shortfall` / `unknown` from the material's accepted fire
+     * and slip facts, in input order; each material also carries a rolled-up
+     * `summary`, and `resolvedContext` reports the axes actually used.
+     *
+     * @example
+     * const advisory = await mg.codes.advisory({
+     *   variantIds: scheme.picks.map((p) => p.variantId),
+     *   jurisdictionId: "us-tx",
+     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
+     *   spaceType: "corridors", // corridors | exit_stairs_passageways | rooms_enclosed_spaces
+     *   sprinklered: true,
+     * });
+     * // `unverified` means no comparable rating is on file — common, never a pass.
+     * const blocked = advisory.results.filter((r) => r.summary?.status === "shortfall");
+     */
+    advisory(input: CodeAdvisoryInput, signal?: AbortSignal): Promise<CodeAdvisoryResponse>;
+}

package/codes-client.js

@@ -0,0 +1,73 @@
+export class CodesClient {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /**
+     * The vocabulary for stating a code context (GET `/api/v1/codes/context`):
+     * seeded jurisdictions and their coverage tier, the occupancy groups the
+     * registry keys on, finish locations, dimensions, classification scales with
+     * classes ordered best-first, and which `ms_room` term correlates to which
+     * regulatory axes.
+     *
+     * Start here — every value the other two calls accept is listed in this one
+     * response, so nothing need be hardcoded. A correlation the registry refuses to
+     * make comes back `null`, never a guess.
+     *
+     * @example
+     * const vocab = await mg.codes.context();
+     * const texas = vocab.jurisdictions.find((j) => j.id === "us-tx");
+     * // `model_baseline` means unamended model IBC stood in for this AHJ's own table.
+     * console.log(texas?.coverage, texas?.adoptionNote);
+     */
+    context(signal) {
+        return this.#transport.get("list_code_context", undefined, signal);
+    }
+    /**
+     * What a space demands, before any candidate exists (GET
+     * `/api/v1/codes/requirements`). State the space by explicit axes, or by a
+     * `roomType` the axes are correlated from.
+     *
+     * An empty `requirements` array means nothing in the registry applies to this
+     * context. It is NOT a pass.
+     *
+     * @example
+     * const { requirements } = await mg.codes.requirements({
+     *   jurisdictionId: "us-tx",
+     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
+     *   spaceType: "corridors",
+     *   sprinklered: true,
+     * });
+     * requirements.map((r) => `${r.dimension}: ${r.label} (${r.section})`);
+     */
+    requirements(input, signal) {
+        return this.#transport.get("list_code_requirements", {
+            jurisdiction: input.jurisdictionId,
+            sprinklered: input.sprinklered,
+            occupancy: input.occupancyGroup,
+            space: input.spaceType,
+            room: input.roomType,
+        }, signal);
+    }
+    /**
+     * Badge materials against the advisory building-code registry for one context
+     * (POST `/api/v1/codes/advisory`, ≤ 100 ids). Each applicable requirement is
+     * badged `meets` / `shortfall` / `unknown` from the material's accepted fire
+     * and slip facts, in input order; each material also carries a rolled-up
+     * `summary`, and `resolvedContext` reports the axes actually used.
+     *
+     * @example
+     * const advisory = await mg.codes.advisory({
+     *   variantIds: scheme.picks.map((p) => p.variantId),
+     *   jurisdictionId: "us-tx",
+     *   occupancyGroup: "A-2", // or: roomType: "hotel_room" to correlate the axes
+     *   spaceType: "corridors", // corridors | exit_stairs_passageways | rooms_enclosed_spaces
+     *   sprinklered: true,
+     * });
+     * // `unverified` means no comparable rating is on file — common, never a pass.
+     * const blocked = advisory.results.filter((r) => r.summary?.status === "shortfall");
+     */
+    advisory(input, signal) {
+        return this.#transport.post("resolveCodeAdvisory", input, signal);
+    }
+}