@instruments/materialgraph 0.1.0 → 0.2.0

package/composition-types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Hand-mirrored wire types for the synchronous composition-variation surface
+ * (`POST /api/v1/schemes/vary`, operation `vary_schemes`, MG-438). Like the rest
+ * of the SDK these interfaces carry NO runtime dependency on any
+ * `@materialgraph/*` package — they mirror the `VarySchemesRequest` /
+ * `VarySchemesResponse` shapes in `apps/web/public/openapi.yaml`.
+ *
+ * Vary is deterministic and synchronous: it re-derives an "option B" from a
+ * succeeded `compose-material-schemes` Run along one constraint axis, so unlike
+ * the async Run surface the response IS the scheme — no run envelope, no events.
+ *
+ * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
+ * so a new server value still type-checks; objects are read structurally.
+ */
+import type { OpenEnum } from "./types.js";
+/**
+ * The four v1 variation axes. Request-side, so this is a STRICT union (the
+ * caller picks exactly one). `uniqueness` is deferred server-side (MG-445).
+ */
+export type VaryAxis = "palette" | "sustainability" | "brandDiversity" | "priceTier";
+/**
+ * The variation axes as a runtime array, for consumers that render an axis
+ * picker. Order is the canonical presentation order.
+ */
+export declare const VARY_AXES: readonly VaryAxis[];
+/** Pin one slot to a specific variant so vary re-derives only the rest. */
+export interface SchemeLock {
+    slotId: string;
+    /** Must equal that slot's CURRENT pick in the source scheme. */
+    variantId: string;
+}
+/** Candidate exclusions applied on top of the automatic source-pick exclusion. */
+export interface SchemeExclusions {
+    variantIds?: string[];
+    brandSlugs?: string[];
+}
+/** Body for `POST /api/v1/schemes/vary` ({@link MaterialGraphClient.varyScheme}). */
+export interface VarySchemesRequest {
+    /** The succeeded `compose-material-schemes` Run to vary from. */
+    runId: string;
+    /** Which scheme in the Run is option A. Defaults to the Run's FIRST scheme. */
+    schemeId?: string;
+    axis: VaryAxis;
+    /** Slots kept pinned to their source pick; only unlocked slots re-derive. */
+    locks?: SchemeLock[];
+    exclusions?: SchemeExclusions;
+}
+export type CompositionMatchState = OpenEnum<"matched" | "mismatched" | "unknown">;
+/** One resolved criterion → material match, as scored during composition. */
+export interface CompositionMatch {
+    attributeId: string;
+    state: CompositionMatchState;
+    confidence: number | null;
+    sourceBasis: string | null;
+}
+/** One slot's chosen material plus the reason it was picked. */
+export interface CompositionPick {
+    slotId: string;
+    slotName: string;
+    spaceId?: string | null;
+    element?: string | null;
+    material: {
+        variantId: string;
+        brand: string;
+        product: string;
+        variant: string;
+        imageUrl: string | null;
+        hex: string | null;
+    };
+    reason: {
+        score: number;
+        matched: CompositionMatch[];
+        notes: string[];
+    };
+}
+/** The multi-objective score for one scheme (each component in [0, 1]). */
+export interface CompositionObjective {
+    total: number;
+    briefFit: number;
+    coverage: number;
+    coherence: number;
+    novelty: number;
+}
+/** A hydrated scheme: one pick per slot, plus its objective breakdown. */
+export interface CompositionScheme {
+    schemeId: string;
+    title: string;
+    picks: CompositionPick[];
+    objective: CompositionObjective;
+}
+/** How far short of the request the derivation fell, with honest reasons. */
+export interface CompositionShortfall {
+    requested: number;
+    produced: number;
+    reasons: string[];
+}
+/** The axis + source provenance stamped onto every varied scheme. */
+export interface VaryProvenance {
+    axis: VaryAxis;
+    sourceRunId: string;
+    sourceSchemeId: string;
+    lockedSlotIds: string[];
+    /**
+     * Human-readable notes recording exactly what the axis did — counts, not
+     * adjectives (e.g. "brandDiversity: hard-excluded 2 brand(s) appearing ≥2×").
+     * These are the variation's receipts.
+     */
+    notes: string[];
+}
+/** The `200` body from `POST /api/v1/schemes/vary`. */
+export interface VarySchemesResponse {
+    /** The composition version the scheme was stamped with. */
+    version: string;
+    scheme: CompositionScheme;
+    provenance: VaryProvenance;
+    shortfall: CompositionShortfall | null;
+}

package/composition-types.js

@@ -0,0 +1,10 @@
+/**
+ * The variation axes as a runtime array, for consumers that render an axis
+ * picker. Order is the canonical presentation order.
+ */
+export const VARY_AXES = Object.freeze([
+    "palette",
+    "sustainability",
+    "brandDiversity",
+    "priceTier",
+]);

package/http-transport.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The shared low-level HTTP transport for {@link MaterialGraphClient}. It owns
+ * URL building, the bearer header, rate-limit capture, response reading, and the
+ * one error-mapping path — so the JSON read surface (`client.ts`), the multipart
+ * upload, and the SSE stream (`runs.ts`) all fail identically. Retry-free by
+ * design; a single failure surfaces as one {@link MaterialGraphError}.
+ */
+import { type RateLimit } from "./errors.js";
+import { type SdkOperation } from "./operations.js";
+export type QueryValue = string | number | boolean | undefined | null | Array<string | number | boolean>;
+export type QueryParams = Record<string, QueryValue>;
+export interface RequestOptions {
+    query?: QueryParams;
+    body?: unknown;
+    signal?: AbortSignal;
+    pathParams?: Readonly<Record<string, string>>;
+}
+/** A read, status-checked HTTP response with its parsed body. */
+export interface SentResponse {
+    response: Response;
+    text: string;
+    parsed: unknown;
+}
+interface SendInput {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    /** The only bodies the SDK sends: a JSON string or a multipart `FormData`. */
+    body?: string | FormData;
+    signal?: AbortSignal;
+}
+export interface HttpTransportOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetch: typeof fetch;
+}
+export declare class HttpTransport {
+    #private;
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly fetch: typeof fetch;
+    constructor(options: HttpTransportOptions);
+    get lastRateLimit(): RateLimit | null;
+    /** The bearer + JSON `Accept` headers, plus any per-request additions. */
+    authHeaders(extra?: Record<string, string>): Record<string, string>;
+    buildUrl(path: string, query?: QueryParams): string;
+    /**
+     * Send one request, capture rate limits, read the body, and map a non-2xx or
+     * transport failure to a {@link MaterialGraphError}. The parsed JSON body (or
+     * raw text when unparseable) is returned on success. Not for streaming reads —
+     * it consumes the whole body via `response.text()`.
+     */
+    send(input: SendInput): Promise<SentResponse>;
+    /** Execute a registered JSON operation and return its typed body. */
+    requestJson<T>(sdkOperation: SdkOperation, options?: RequestOptions): Promise<T>;
+}
+export {};

package/http-transport.js

@@ -0,0 +1,131 @@
+/**
+ * The shared low-level HTTP transport for {@link MaterialGraphClient}. It owns
+ * URL building, the bearer header, rate-limit capture, response reading, and the
+ * one error-mapping path — so the JSON read surface (`client.ts`), the multipart
+ * upload, and the SSE stream (`runs.ts`) all fail identically. Retry-free by
+ * design; a single failure surfaces as one {@link MaterialGraphError}.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { operationPath } from "./operations.js";
+function parseIntOrNull(value) {
+    if (value === null)
+        return null;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+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 HttpTransport {
+    baseUrl;
+    apiKey;
+    fetch;
+    #lastRateLimit = null;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.fetch = options.fetch;
+    }
+    get lastRateLimit() {
+        return this.#lastRateLimit;
+    }
+    /** The bearer + JSON `Accept` headers, plus any per-request additions. */
+    authHeaders(extra) {
+        return { Authorization: `Bearer ${this.apiKey}`, Accept: "application/json", ...extra };
+    }
+    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();
+    }
+    /**
+     * Send one request, capture rate limits, read the body, and map a non-2xx or
+     * transport failure to a {@link MaterialGraphError}. The parsed JSON body (or
+     * raw text when unparseable) is returned on success. Not for streaming reads —
+     * it consumes the whole body via `response.text()`.
+     */
+    async send(input) {
+        const requestUrl = new URL(input.url);
+        const metadata = {
+            method: input.method,
+            origin: requestUrl.origin,
+            path: requestUrl.pathname,
+        };
+        let response;
+        try {
+            response = await this.fetch(input.url, {
+                method: input.method,
+                headers: input.headers,
+                body: input.body,
+                signal: input.signal,
+            });
+        }
+        catch (cause) {
+            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: input.signal });
+        }
+        const rateLimit = parseRateLimit(response.headers);
+        this.#lastRateLimit = rateLimit;
+        let text;
+        try {
+            text = await response.text();
+        }
+        catch (cause) {
+            throw MaterialGraphError.fromTransport({ ...metadata, cause, callerSignal: input.signal });
+        }
+        let parsed;
+        if (text.length > 0) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!response.ok) {
+            throw MaterialGraphError.fromResponse({
+                ...metadata,
+                status: response.status,
+                body: parsed,
+                responseText: text,
+                rateLimit,
+                apiKey: this.apiKey,
+                queryValues: [...requestUrl.searchParams.values()],
+            });
+        }
+        return { response, text, parsed };
+    }
+    /** Execute a registered JSON operation and return its typed body. */
+    async requestJson(sdkOperation, options = {}) {
+        const url = this.buildUrl(operationPath(sdkOperation, options.pathParams), options.query);
+        const hasBody = options.body !== undefined;
+        const { parsed } = await this.send({
+            method: sdkOperation.method,
+            url,
+            headers: this.authHeaders(hasBody ? { "Content-Type": "application/json" } : undefined),
+            body: hasBody ? JSON.stringify(options.body) : undefined,
+            signal: options.signal,
+        });
+        return parsed;
+    }
+}

package/index.d.ts

@@ -2,11 +2,23 @@ export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.j
 export type { MaterialGraphClientOptions, BrowseNamespace } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
 export type { SdkOperation, SdkOperationId } from "./operations.js";
+export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
+export type * from "./run-types.js";
+export { VARY_AXES } from "./composition-types.js";
+export type * from "./composition-types.js";
+export { PROJECT_EVENT_KINDS } from "./project-types.js";
+export type * from "./project-types.js";
+export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
+export type * from "./run-events.js";
 export { MaterialGraphError } from "./errors.js";
 export type { MaterialGraphErrorInit, MaterialGraphErrorKind, MaterialGraphRequestMetadata, ProblemDetail, RateLimit, SanitizedErrorValue, SanitizedIssue, SimpleErrorBody, } from "./errors.js";
 export type * from "./types.js";
+export type * from "./codes-types.js";
 export type * from "./brand-types.js";
 export type * from "./material-asset-types.js";
 export type * from "./material-block-types.js";
 export type * from "./schema-resource-types.js";
 export type * from "./search-refinement-types.js";
+export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
+export type * from "./spec-types.js";
+export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specTerm, } from "./specifications.js";

package/index.js

@@ -1,3 +1,9 @@
 export { MaterialGraphClient, DEFAULT_BASE_URL, MAX_BATCH_IDS } from "./client.js";
 export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS } from "./operations.js";
+export { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
+export { VARY_AXES } from "./composition-types.js";
+export { PROJECT_EVENT_KINDS } from "./project-types.js";
+export { COMPOSITION_PHASE_EVENT_TYPES, COMPOSITION_PROGRAMME_EVENT_TYPES, COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, parseRunEvent, } from "./run-events.js";
 export { MaterialGraphError } from "./errors.js";
+export { CERTIFICATION_PROGRAMME_ATTRIBUTE_ID } from "./spec-types.js";
+export { certificationProgramme, certificationProgrammeCriterion, hasSpec, specCriterion, specTerm, } from "./specifications.js";

package/operations.d.ts

@@ -1,5 +1,5 @@
-export declare const MATERIALGRAPH_API_VERSION = "0.6.0";
-declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{slug}", "get_brand_profile"]];
+export declare const MATERIALGRAPH_API_VERSION = "0.7.0";
+declare const OPERATION_DEFINITIONS: readonly [readonly ["search", "POST", "/api/v1/search", "search_materials_post"], readonly ["searchGet", "GET", "/api/v1/search", "search_materials_get"], readonly ["match", "POST", "/api/v1/search/match", "match_material"], readonly ["byColour", "GET", "/api/v1/search/colours", "search_by_colour"], readonly ["material", "GET", "/api/v1/materials/{variantId}", "get_material"], readonly ["siblings", "GET", "/api/v1/materials/{variantId}/siblings", "get_material_siblings"], readonly ["materialBlocks", "GET", "/api/v1/materials/{variantId}/blocks", "list_material_blocks"], readonly ["materialAssets", "GET", "/api/v1/materials/{variantId}/assets", "list_material_assets"], readonly ["schema", "GET", "/api/v1/schema/blocks", "list_schema_blocks"], readonly ["schema", "GET", "/api/v1/schema/attributes", "list_schema_attributes"], readonly ["schema", "GET", "/api/v1/schema/verticals", "list_schema_verticals"], readonly ["schema", "GET", "/api/v1/schema/product-types", "list_schema_product_types"], readonly ["schema", "GET", "/api/v1/schema/units", "list_schema_units"], readonly ["schema", "GET", "/api/v1/schema/value-dictionaries", "list_schema_value_dictionaries"], readonly ["schema", "GET", "/api/v1/schema/source-requirements", "list_schema_source_requirements"], readonly ["schema", "GET", "/api/v1/schema/product-type-templates", "list_schema_product_type_templates"], readonly ["schema", "GET", "/api/v1/schema/mappings", "list_schema_mappings"], readonly ["pairings", "GET", "/api/v1/materials/{variantId}/pairings", "get_material_pairings"], readonly ["materials", "POST", "/api/v1/materials/batch", "get_materials_batch_post"], readonly ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"], readonly ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"], readonly ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"], readonly ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"], readonly ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"], readonly ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"], readonly ["resolveAttributeValue", "GET", "/api/v1/catalog/attributes/{attributeId}/values/resolve", "catalog_resolve_value"], readonly ["searchVocabulary", "GET", "/api/v1/catalog/vocabulary/search", "catalog_vocabulary_search"], readonly ["bySpec", "GET", "/api/v1/search/specifications", "catalog_by_spec"], readonly ["taxonomy", "GET", "/api/v1/taxonomy/categories", "get_category_taxonomy"], readonly ["whoami", "GET", "/api/v1/whoami", "whoami"], readonly ["coordinate", "POST", "/api/v1/pairings/coordinate", "coordinate_materials"], readonly ["demand", "GET", "/api/v1/demand", "get_material_demand"], readonly ["extractPalette", "POST", "/api/v1/search/palettes/extract", "extract_image_palette"], readonly ["specificationFacets", "GET", "/api/v1/catalog/specifications/facets", "list_spec_facets"], readonly ["attributeValues", "GET", "/api/v1/catalog/attributes/{attributeId}/values", "list_attribute_values"], readonly ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"], readonly ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"], readonly ["brands", "GET", "/api/v1/brands", "list_brands"], readonly ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"], readonly ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"], readonly ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"], readonly ["createRun", "POST", "/api/v1/runs", "create_public_run"], readonly ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"], readonly ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"], readonly ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"], readonly ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"], readonly ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"], readonly ["createProject", "POST", "/api/v1/projects", "create_box_project"], readonly ["listProjects", "GET", "/api/v1/projects", "list_box_projects"], readonly ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"], readonly ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"], readonly ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"], readonly ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"]];
 export type SdkOperationId = (typeof OPERATION_DEFINITIONS)[number][3];
 export type SdkOperation = Readonly<{
     clientMethod: (typeof OPERATION_DEFINITIONS)[number][0];
@@ -8,4 +8,8 @@ export type SdkOperation = Readonly<{
     operationId: SdkOperationId;
 }>;
 export declare const SDK_OPERATIONS: readonly SdkOperation[];
+/** Look up a registered operation by its OpenAPI `operationId`. */
+export declare function findSdkOperation(operationId: SdkOperationId): SdkOperation | undefined;
+/** Substitute `{param}` path placeholders with percent-encoded values. */
+export declare function operationPath(sdkOperation: SdkOperation, pathParams?: Readonly<Record<string, string>>): string;
 export {};

package/operations.js

@@ -1,4 +1,4 @@
-export const MATERIALGRAPH_API_VERSION = "0.6.0";
+export const MATERIALGRAPH_API_VERSION = "0.7.0";
 const OPERATION_DEFINITIONS = [
     ["search", "POST", "/api/v1/search", "search_materials_post"],
     ["searchGet", "GET", "/api/v1/search", "search_materials_get"],
@@ -48,6 +48,28 @@ const OPERATION_DEFINITIONS = [
     ["applicableSpecs", "GET", "/api/v1/taxonomy/categories/{key}/specs", "get_applicable_specs"],
     ["glossary", "GET", "/api/v1/glossary/{term}", "explain_material_term"],
     ["brands", "GET", "/api/v1/brands", "list_brands"],
-    ["brand", "GET", "/api/v1/brands/{slug}", "get_brand_profile"],
+    ["brand", "GET", "/api/v1/brands/{brandSlug}", "get_brand_profile"],
+    ["uploadSourceMaterial", "POST", "/api/v1/source-material", "upload_source_material"],
+    ["capabilities", "GET", "/api/v1/capabilities", "list_public_capabilities"],
+    ["createRun", "POST", "/api/v1/runs", "create_public_run"],
+    ["run", "GET", "/api/v1/runs/{runId}", "get_public_run"],
+    ["streamRunEvents", "GET", "/api/v1/runs/{runId}/events", "list_public_run_events"],
+    ["resumeRun", "POST", "/api/v1/runs/{runId}/resume", "resume_public_run"],
+    ["cancelRun", "POST", "/api/v1/runs/{runId}/cancel", "cancel_public_run"],
+    ["varyScheme", "POST", "/api/v1/schemes/vary", "vary_schemes"],
+    ["createProject", "POST", "/api/v1/projects", "create_box_project"],
+    ["listProjects", "GET", "/api/v1/projects", "list_box_projects"],
+    ["getProject", "GET", "/api/v1/projects/{projectId}", "get_box_project"],
+    ["appendProjectEvent", "POST", "/api/v1/projects/{projectId}/events", "append_box_project_event"],
+    ["demandBatch", "POST", "/api/v1/demand/batch", "get_demand_batch"],
+    ["codeAdvisory", "POST", "/api/v1/codes/advisory", "resolveCodeAdvisory"],
 ];
 export const SDK_OPERATIONS = Object.freeze(OPERATION_DEFINITIONS.map(([clientMethod, method, path, operationId]) => Object.freeze({ clientMethod, method, path, operationId })));
+/** Look up a registered operation by its OpenAPI `operationId`. */
+export function findSdkOperation(operationId) {
+    return SDK_OPERATIONS.find((candidate) => candidate.operationId === operationId);
+}
+/** Substitute `{param}` path placeholders with percent-encoded values. */
+export function operationPath(sdkOperation, pathParams = {}) {
+    return Object.entries(pathParams).reduce((path, [name, value]) => path.replace(`{${name}}`, encodeURIComponent(value)), sdkOperation.path);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {

package/project-types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Wire types for the persistent Material Box project surface (`/api/v1/projects`).
+ * Hand-mirrored from `@materialgraph/products/projects`' Zod contract — the SDK
+ * has zero runtime dependency on `@materialgraph/*`. Kept shape-identical to the
+ * server contract; the OpenAPI parity test gates method/path/operationId, and the
+ * server route schemas gate the body shapes.
+ */
+/** The six governed project-event kinds. */
+export type ProjectEventKind = "batch-attached" | "run-started" | "clarifying-answer" | "pairwise-preference" | "reference-chosen" | "scheme-adopted";
+/** The frozen tuple of every project-event kind, for enumeration. */
+export declare const PROJECT_EVENT_KINDS: readonly ProjectEventKind[];
+/** One clarifying question and the designer's answer. */
+export interface ClarifyingAnswer {
+    question: string;
+    answer: string;
+}
+/** One pairwise preference; `chosenId` is `leftId` or `rightId`. */
+export interface PairwisePreference {
+    leftId: string;
+    rightId: string;
+    chosenId: string;
+}
+/** One stored event; `payload` is validated to the shape of `kind`. */
+export interface ProjectEvent {
+    eventId: string;
+    kind: ProjectEventKind;
+    payload: Record<string, unknown>;
+    createdAt: string;
+}
+/** A lightweight project row for list views (no event fold). */
+export interface ProjectSummary {
+    projectId: string;
+    principalId: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A project's assembled read model — identity plus the folded event collections. */
+export interface ProjectState extends ProjectSummary {
+    batchIds: string[];
+    runIds: string[];
+    answers: ClarifyingAnswer[];
+    preferences: PairwisePreference[];
+    chosenReferences: string[];
+    adoptedSchemes: string[];
+    events: ProjectEvent[];
+}
+/** `GET /api/v1/projects` — the caller's projects, newest first. */
+export interface ProjectListResponse {
+    projects: ProjectSummary[];
+}
+/** `POST /api/v1/projects` request body. */
+export interface CreateProjectRequest {
+    name?: string;
+}
+/** `POST /api/v1/projects/{projectId}/events` request body. */
+export interface AppendProjectEventRequest {
+    kind: ProjectEventKind;
+    payload: Record<string, unknown>;
+}
+/** `POST /api/v1/projects/{projectId}/events` response — the appended event receipt. */
+export interface ProjectEventReceipt {
+    eventId: string;
+    projectId: string;
+    kind: ProjectEventKind;
+    createdAt: string;
+}

package/project-types.js

@@ -0,0 +1,16 @@
+/**
+ * Wire types for the persistent Material Box project surface (`/api/v1/projects`).
+ * Hand-mirrored from `@materialgraph/products/projects`' Zod contract — the SDK
+ * has zero runtime dependency on `@materialgraph/*`. Kept shape-identical to the
+ * server contract; the OpenAPI parity test gates method/path/operationId, and the
+ * server route schemas gate the body shapes.
+ */
+/** The frozen tuple of every project-event kind, for enumeration. */
+export const PROJECT_EVENT_KINDS = Object.freeze([
+    "batch-attached",
+    "run-started",
+    "clarifying-answer",
+    "pairwise-preference",
+    "reference-chosen",
+    "scheme-adopted",
+]);

package/projects.d.ts

@@ -0,0 +1,13 @@
+import { HttpTransport } from "./http-transport.js";
+import type { AppendProjectEventRequest, CreateProjectRequest, ProjectEventReceipt, ProjectListResponse, ProjectState } from "./project-types.js";
+/** Create a project (`POST /api/v1/projects`). Requires the `mg:ingest` scope. */
+export declare function createProject(transport: HttpTransport, body?: CreateProjectRequest, signal?: AbortSignal): Promise<ProjectState>;
+/** Read a project's assembled state (`GET /api/v1/projects/{projectId}`). */
+export declare function getProject(transport: HttpTransport, projectId: string, signal?: AbortSignal): Promise<ProjectState>;
+/**
+ * Append one event to a project's process trail
+ * (`POST /api/v1/projects/{projectId}/events`). Requires the `mg:ingest` scope.
+ */
+export declare function appendProjectEvent(transport: HttpTransport, projectId: string, body: AppendProjectEventRequest, signal?: AbortSignal): Promise<ProjectEventReceipt>;
+/** List your own projects, newest first (`GET /api/v1/projects`). */
+export declare function listProjects(transport: HttpTransport, signal?: AbortSignal): Promise<ProjectListResponse>;

package/projects.js

@@ -0,0 +1,46 @@
+/**
+ * The persistent-project namespace of the SDK. Thin wrappers over the shared
+ * {@link HttpTransport} for the `/api/v1/projects` surface: create a project,
+ * read its assembled state, append process-trail events, and list your own.
+ * Box's proxy routes are thin wrappers over exactly these calls.
+ */
+import { MaterialGraphError } from "./errors.js";
+import { HttpTransport } from "./http-transport.js";
+import { findSdkOperation } from "./operations.js";
+function projectOperation(operationId) {
+    const match = findSdkOperation(operationId);
+    if (!match)
+        throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
+    return match;
+}
+/** Create a project (`POST /api/v1/projects`). Requires the `mg:ingest` scope. */
+export function createProject(transport, body = {}, signal) {
+    return transport.requestJson(projectOperation("create_box_project"), {
+        body,
+        signal,
+    });
+}
+/** Read a project's assembled state (`GET /api/v1/projects/{projectId}`). */
+export function getProject(transport, projectId, signal) {
+    return transport.requestJson(projectOperation("get_box_project"), {
+        pathParams: { projectId },
+        signal,
+    });
+}
+/**
+ * Append one event to a project's process trail
+ * (`POST /api/v1/projects/{projectId}/events`). Requires the `mg:ingest` scope.
+ */
+export function appendProjectEvent(transport, projectId, body, signal) {
+    return transport.requestJson(projectOperation("append_box_project_event"), {
+        body,
+        pathParams: { projectId },
+        signal,
+    });
+}
+/** List your own projects, newest first (`GET /api/v1/projects`). */
+export function listProjects(transport, signal) {
+    return transport.requestJson(projectOperation("list_box_projects"), {
+        signal,
+    });
+}