@instruments/materialgraph 0.1.0 → 0.3.0

package/ndjson.js

@@ -0,0 +1,103 @@
+/**
+ * A minimal, dependency-free NDJSON (newline-delimited JSON) line reader — the
+ * primitive behind {@link MaterialGraphClient.matchStream}. Hand-rolled so the
+ * SDK stays zero-runtime-dep and works unchanged inside Node route handlers,
+ * where `fetch` yields a byte `ReadableStream`.
+ *
+ * Deliberately a SIBLING of `sse.ts`, not a reuse of it. NDJSON and SSE agree on
+ * nothing but "text arrives in chunks": SSE frames are `field: value` lines
+ * terminated by a BLANK line, with comment lines and multi-line `data:`
+ * accumulation, whereas an NDJSON frame is exactly one line of JSON. Feeding
+ * NDJSON through the SSE tokenizer would read `{"type":"step",…}` as a field
+ * named `{"type"` and silently discard every frame. The two also want OPPOSITE
+ * end-of-stream policies: SSE dispatches a trailing partial frame as valid,
+ * while a truncated NDJSON line must surface as an error (enforced by the
+ * caller, which parses whatever `flush` returns rather than dropping it).
+ *
+ * Line endings: the reader splits on `\n` only, per the NDJSON contract. A `\r`
+ * left by a CRLF-normalising proxy stays as trailing whitespace on the line,
+ * which `JSON.parse` ignores.
+ */
+/**
+ * A push-based NDJSON line assembler. Feed it decoded text with {@link push};
+ * it returns the lines that text COMPLETED, terminators removed. Any partial
+ * trailing line is held in an internal buffer until a later chunk terminates it,
+ * or until {@link flush} surrenders it at end of stream.
+ */
+export class NdjsonDecoder {
+    #buffer = "";
+    /** Absorb one decoded chunk and return the lines it completed, in order. */
+    push(text) {
+        this.#buffer += text;
+        const lines = [];
+        for (;;) {
+            const index = this.#buffer.indexOf("\n");
+            if (index === -1)
+                break;
+            lines.push(this.#buffer.slice(0, index));
+            this.#buffer = this.#buffer.slice(index + 1);
+        }
+        return lines;
+    }
+    /**
+     * Surrender the unterminated remainder at end of stream — a well-formed
+     * NDJSON stream's final line need not carry a trailing newline. The remainder
+     * is RETURNED, never dropped: a truncated frame is the caller's error to
+     * raise, not this decoder's fragment to discard.
+     */
+    flush() {
+        if (this.#buffer.length === 0)
+            return [];
+        const remainder = this.#buffer;
+        this.#buffer = "";
+        return [remainder];
+    }
+}
+/**
+ * Iterate the NDJSON lines of a byte stream. Only lines with non-whitespace
+ * content are yielded — a blank separator line carries no frame and must never
+ * reach `JSON.parse`, where it would become an empty object. Stops cleanly when
+ * the stream ends or `signal` aborts (mid-read abort rejections are swallowed
+ * once the signal is set).
+ */
+export async function* readNdjsonLines(body, signal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    const ndjson = new NdjsonDecoder();
+    try {
+        for (;;) {
+            if (signal?.aborted)
+                return;
+            let result;
+            try {
+                result = await reader.read();
+            }
+            catch (error) {
+                if (signal?.aborted)
+                    return;
+                throw error;
+            }
+            if (result.done) {
+                // `decode()` with no argument flushes any dangling multi-byte sequence.
+                for (const line of ndjson.push(decoder.decode())) {
+                    if (line.trim().length > 0)
+                        yield line;
+                }
+                for (const line of ndjson.flush()) {
+                    if (line.trim().length > 0)
+                        yield line;
+                }
+                return;
+            }
+            for (const line of ndjson.push(decoder.decode(result.value, { stream: true }))) {
+                if (signal?.aborted)
+                    return;
+                if (line.trim().length > 0)
+                    yield line;
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

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 ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"], readonly ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"], 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 ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"], 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 ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"], 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"], readonly ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"], readonly ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"]];
 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"],
@@ -22,6 +22,8 @@ const OPERATION_DEFINITIONS = [
     ["materialsCached", "GET", "/api/v1/materials/batch", "get_materials_batch_get"],
     ["browse", "GET", "/api/v1/search/browse", "search_browse_by_colour"],
     ["colourFacets", "GET", "/api/v1/colours/facets", "get_colour_facets"],
+    ["colours.profiles", "GET", "/api/v1/colours/profiles", "get_category_colour_profiles"],
+    ["colours.stats", "GET", "/api/v1/colours/stats", "get_colour_stats"],
     ["resolveColour", "GET", "/api/v1/search/colours/resolve", "resolve_colour_name"],
     ["suggestColour", "GET", "/api/v1/search/colours/suggest", "suggest_colour_names"],
     ["resolveAttribute", "GET", "/api/v1/catalog/attributes/resolve", "catalog_resolve_attribute"],
@@ -48,6 +50,32 @@ 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"],
+    ["sourceMaterialBatch", "GET", "/api/v1/source-material/{batchId}", "get_source_material_batch"],
+    ["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"],
+    ["runSchedule", "GET", "/api/v1/runs/{runId}/schedule", "get_run_finish_schedule"],
+    ["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"],
+    ["codes.context", "GET", "/api/v1/codes/context", "list_code_context"],
+    ["codes.requirements", "GET", "/api/v1/codes/requirements", "list_code_requirements"],
 ];
 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.3.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,
+    });
+}

package/run-events.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Typed payloads for the composition Run event family — the friction fix flagged
+ * by the MG-443 walk. These narrow the loose {@link RunEvent.payloadJson} so
+ * consumers (the Box console) can render phase progress, the parsed programme,
+ * and the criteria-correction UI without re-typing each payload at the call
+ * site.
+ *
+ * Both wire generations are covered: the CURRENT `composition.*` strings the
+ * server emits today, and the LEGACY `material-box.*` strings kept for read-side
+ * dual-read compatibility. Shapes mirror
+ * `packages/mastra/src/workflow/composition/events.ts` and the
+ * `reviewCriteriaSuspendPayloadSchema` in `@materialgraph/products` — expressed
+ * as standalone TS types (no cross-package import; the SDK is publishable).
+ */
+import type { OpenEnum } from "./types.js";
+import type { RunEvent } from "./run-types.js";
+export declare const COMPOSITION_PHASE_EVENT_TYPES: readonly ["composition.phase", "material-box.phase"];
+export declare const COMPOSITION_PROGRAMME_EVENT_TYPES: readonly ["composition.programme", "material-box.brief"];
+export declare const COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES: readonly ["composition.review-criteria", "material-box.review-criteria"];
+export type CompositionPhaseEventType = (typeof COMPOSITION_PHASE_EVENT_TYPES)[number];
+export type CompositionProgrammeEventType = (typeof COMPOSITION_PROGRAMME_EVENT_TYPES)[number];
+export type CompositionReviewCriteriaEventType = (typeof COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES)[number];
+/** Payload of a `composition.phase` / `material-box.phase` progress event. */
+export interface CompositionPhasePayload {
+    workflow: OpenEnum<"parse-material-brief" | "compose-material-schemes">;
+    phase: string;
+    label: string;
+    state: OpenEnum<"started" | "completed" | "failed">;
+    /** Additive narration (file names, error messages); absent on older events. */
+    detail?: string;
+    /** Additive tallies (slot/candidate/scheme counts); absent on older events. */
+    counts?: Record<string, number>;
+}
+/**
+ * Payload of a `composition.programme` / `material-box.brief` event. The current
+ * generation carries `programme`; the legacy generation carried `brief`. Both
+ * are read structurally (the parsed programme document).
+ */
+export interface CompositionProgrammePayload {
+    programme?: unknown;
+    brief?: unknown;
+}
+/** One unresolved brief phrase offered for human correction at the review step. */
+export interface CompositionReviewCriteriaSuggestion {
+    attributeId: string;
+    name: string;
+    term?: string;
+    score: number;
+}
+export interface CompositionReviewCriteriaUnresolved {
+    slotId: string;
+    raw: string;
+    suggestions: CompositionReviewCriteriaSuggestion[];
+}
+/**
+ * Payload of a `composition.review-criteria` / `material-box.review-criteria`
+ * suspend event — the correction grammar the Box review step renders.
+ */
+export interface CompositionReviewCriteriaPayload {
+    unresolved: CompositionReviewCriteriaUnresolved[];
+}
+export interface CompositionPhaseEvent extends RunEvent {
+    type: CompositionPhaseEventType;
+    payloadJson: CompositionPhasePayload;
+}
+export interface CompositionProgrammeEvent extends RunEvent {
+    type: CompositionProgrammeEventType;
+    payloadJson: CompositionProgrammePayload;
+}
+export interface CompositionReviewCriteriaEvent extends RunEvent {
+    type: CompositionReviewCriteriaEventType;
+    payloadJson: CompositionReviewCriteriaPayload;
+}
+/** The discriminated union of all composition Run events. */
+export type CompositionEvent = CompositionPhaseEvent | CompositionProgrammeEvent | CompositionReviewCriteriaEvent;
+/**
+ * Narrow a {@link RunEvent} to the composition family by its `type`, returning
+ * `null` for lifecycle events (`queued`, `running`, `succeeded`, …) and any
+ * unknown type. Narrowing is by the discriminating `type` only — payloads are
+ * trusted structurally per the tolerant-parsing contract, never re-validated.
+ */
+export declare function parseRunEvent(event: RunEvent): CompositionEvent | null;

package/run-events.js

@@ -0,0 +1,29 @@
+// ── Wire event-type strings (both generations) ───────────────────────────────
+export const COMPOSITION_PHASE_EVENT_TYPES = ["composition.phase", "material-box.phase"];
+export const COMPOSITION_PROGRAMME_EVENT_TYPES = [
+    "composition.programme",
+    "material-box.brief",
+];
+export const COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES = [
+    "composition.review-criteria",
+    "material-box.review-criteria",
+];
+const includesType = (types, type) => types.includes(type);
+/**
+ * Narrow a {@link RunEvent} to the composition family by its `type`, returning
+ * `null` for lifecycle events (`queued`, `running`, `succeeded`, …) and any
+ * unknown type. Narrowing is by the discriminating `type` only — payloads are
+ * trusted structurally per the tolerant-parsing contract, never re-validated.
+ */
+export function parseRunEvent(event) {
+    if (includesType(COMPOSITION_PHASE_EVENT_TYPES, event.type)) {
+        return event;
+    }
+    if (includesType(COMPOSITION_PROGRAMME_EVENT_TYPES, event.type)) {
+        return event;
+    }
+    if (includesType(COMPOSITION_REVIEW_CRITERIA_EVENT_TYPES, event.type)) {
+        return event;
+    }
+    return null;
+}