@instruments/materialgraph 0.28.0 → 0.30.0

package/workflows-client.d.ts

@@ -0,0 +1,54 @@
+import type { HttpTransport } from "./http-transport.js";
+/**
+ * The workflow Run surface, namespaced as `mg.workflows`. A Run is the start of
+ * one registered Mastra workflow and nothing else: you name the workflow, hand
+ * it its input, and follow the Run it returns. Replaces the flat `createRun()`,
+ * `run()`, `streamRunEvents()` and `drainRunEvents()` methods, retired with no
+ * shim when `/api/v1/runs` moved under `/api/v1/workflows/{workflowId}/runs`.
+ *
+ * THE QUESTION: "do a whole job for me" — the ASYNC lens. Everything else on
+ * the client answers in one round trip; a Run may suspend for human input and
+ * finish minutes later. `start()` acknowledges without executing, `run()` polls
+ * the ledger, and `streamRunEvents()` follows it live.
+ *
+ * `workflowId` is the registered workflow's id, such as `curate-collection`. A
+ * Run is read under the workflow that started it: asking for it under another
+ * workflow's id is a 404.
+ *
+ * Starting a Run needs the `mg:compose` or `mg:write` scope, plus whatever
+ * scope the workflow itself declares.
+ */
+import type { RunId } from "./identifiers.js";
+import type { CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, RunEvent, StreamRunEventsOptions } from "./run-types.js";
+export declare class WorkflowsClient {
+    #private;
+    constructor(options: {
+        transport: HttpTransport;
+    });
+    /**
+     * Start an asynchronous Run of `workflowId` (POST
+     * `/api/v1/workflows/{workflowId}/runs`). Pass `idempotencyKey` so a retry
+     * replays rather than duplicates. Follow with {@link streamRunEvents} (live)
+     * or {@link run} (poll).
+     */
+    start(workflowId: string, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
+    /**
+     * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
+     * ledger record. Polling; prefer {@link streamRunEvents} when a human is
+     * waiting.
+     */
+    run(workflowId: string, runId: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
+    /**
+     * Stream ordered Run events as an async iterator (GET
+     * `/api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until
+     * the stream ends or the signal aborts; pass `after` to resume from the last
+     * observed sequence.
+     */
+    streamRunEvents(workflowId: string, runId: RunId, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent>;
+    /**
+     * 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(workflowId: string, runId: RunId, options: DrainRunEventsOptions): Promise<RunEvent[]>;
+}

package/workflows-client.js

@@ -0,0 +1,41 @@
+import { drainRunEvents, getWorkflowRun, startWorkflowRun, streamRunEvents, } from "./runs.js";
+export class WorkflowsClient {
+    #transport;
+    constructor(options) {
+        this.#transport = options.transport;
+    }
+    /**
+     * Start an asynchronous Run of `workflowId` (POST
+     * `/api/v1/workflows/{workflowId}/runs`). Pass `idempotencyKey` so a retry
+     * replays rather than duplicates. Follow with {@link streamRunEvents} (live)
+     * or {@link run} (poll).
+     */
+    async start(workflowId, body, signal) {
+        return await startWorkflowRun(this.#transport, workflowId, body, signal);
+    }
+    /**
+     * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
+     * ledger record. Polling; prefer {@link streamRunEvents} when a human is
+     * waiting.
+     */
+    async run(workflowId, runId, signal) {
+        return await getWorkflowRun(this.#transport, workflowId, runId, signal);
+    }
+    /**
+     * Stream ordered Run events as an async iterator (GET
+     * `/api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until
+     * the stream ends or the signal aborts; pass `after` to resume from the last
+     * observed sequence.
+     */
+    streamRunEvents(workflowId, runId, options) {
+        return streamRunEvents(this.#transport, workflowId, runId, options);
+    }
+    /**
+     * Collect Run events until a terminal event, the deadline, or the stream
+     * ends — the bounded events-log pattern (a single pass over
+     * {@link streamRunEvents}).
+     */
+    async drainRunEvents(workflowId, runId, options) {
+        return await drainRunEvents(this.#transport, workflowId, runId, options);
+    }
+}

package/client-source-material-comments.d.ts

@@ -1,51 +0,0 @@
-/**
- * The per-file comment surface, namespaced as `mg.sourceMaterialComments` — the
- * argument people leave on one uploaded file (MG-1345).
- *
- * A namespace rather than two more flat methods on an already-large facade,
- * following `mg.codes` and `mg.colours`: reading a thread and adding to it are
- * one family, they share a `(batchId, sourceId)` referent, and neither makes
- * sense without the other. The namespace holds no transport of its own — the
- * client hands it the shared one, so auth, rate-limit accounting and error
- * shaping stay in one place.
- *
- * TWO RULES A CONSUMER MUST NOT GET WRONG.
- *
- * **The author name is REPORTED, never verified.** Every comment carries
- * `author.attribution: "reported"` — a name somebody typed — plus `recordedBy`,
- * the authenticated principal that actually wrote the row. Render "recorded as
- * from Ruth Fielding", never "Ruth Fielding said". The API takes a machine key,
- * and the person whose argument a remark carries is usually not the person at
- * the keyboard; presenting the one as the other is the failure this field
- * exists to prevent.
- *
- * **A reply is not a root.** {@link SourceMaterialCommentsNamespace.post}
- * returns a result discriminated on `kind`: switch on it rather than reaching
- * for `replies`, which a `reply` does not have. Threads are one level deep and
- * the database enforces it, so a reply can never grow replies of its own.
- *
- * ROUTING OUT OF THIS NAMESPACE. `mg.sourceMaterialBatch(batchId)` already
- * inlines every file's thread, so opening a batch is ONE call — do not loop this
- * namespace over a batch's files to rebuild what that read returns. Reach for
- * `list` when you are watching a single file.
- */
-import type { HttpTransport } from "./http-transport.js";
-import type { PostSourceMaterialCommentInput, PostSourceMaterialCommentResult, SourceMaterialCommentThread } from "./run-types.js";
-export type SourceMaterialCommentsNamespace = {
-    /**
-     * One file's thread, oldest root first, each root carrying its replies.
-     * `comments` is always an array; `truncated` says whether you are holding the
-     * whole thread. A file that is not in that batch, or a batch you do not own,
-     * raises the same 404 as a file that never existed.
-     */
-    list(batchId: string, sourceId: string, signal?: AbortSignal): Promise<SourceMaterialCommentThread>;
-    /**
-     * Add one remark. Pass `parentCommentId` to answer a ROOT comment on the same
-     * file; nesting deeper is a 400. Pass `idempotencyKey` so a retry after a
-     * network timeout returns the comment you already posted rather than a
-     * permanent duplicate.
-     */
-    post(batchId: string, sourceId: string, input: PostSourceMaterialCommentInput, signal?: AbortSignal): Promise<PostSourceMaterialCommentResult>;
-};
-/** Bind the comment operations to the client's shared transport. */
-export declare const createSourceMaterialCommentsNamespace: (transport: HttpTransport) => SourceMaterialCommentsNamespace;

package/client-source-material-comments.js

@@ -1,6 +0,0 @@
-import { listSourceMaterialComments, postSourceMaterialComment, } from "./runs.js";
-/** Bind the comment operations to the client's shared transport. */
-export const createSourceMaterialCommentsNamespace = (transport) => ({
-    list: async (batchId, sourceId, signal) => await listSourceMaterialComments(transport, batchId, sourceId, signal),
-    post: async (batchId, sourceId, input, signal) => await postSourceMaterialComment(transport, batchId, sourceId, input, signal),
-});

package/codes-client.d.ts

@@ -1,118 +0,0 @@
-/**
- * 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.
- *
- * ROUTING. Codes answers "is this material allowed in THIS SPACE?" — a question
- * about a jurisdiction, an occupancy group and a finish location, not about a
- * material alone.
- * - "which materials carry Class A?" → `mg.bySpec("fire_classifications:...")`.
- *   That is a property question; this namespace is what tells you the space
- *   demands Class A in the first place.
- * - "what does this one material hold?" → `mg.materialBlocks(variantId)`.
- * - "find me something like this, but compliant" → `mg.search({ filters })`
- *   once `requirements()` has told you which filter to apply.
- */
-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 type 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 QUESTION: "what may I even say about a space?" — the vocabulary for
-     * stating a code context, and the first call of the three.
-     *
-     * Everything {@link CodesClient.requirements} and {@link CodesClient.advisory}
-     * accept is listed here, so nothing need be hardcoded and a 400 for an unknown
-     * jurisdiction / occupancy / space is always avoidable.
-     *
-     * 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 `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>;
-    /**
-     * THE QUESTION: "what does this space DEMAND?" — before any candidate exists.
-     *
-     * Run it before shortlisting, not after: it tells you which specification to
-     * filter on, which you then spend on `mg.bySpec()` or `mg.search({ filters })`.
-     * Use {@link CodesClient.advisory} once you hold candidates to badge.
-     *
-     * 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>;
-    /**
-     * THE QUESTION: "do THESE candidates satisfy what this space demands?" — the
-     * third call, once you hold materials.
-     *
-     * Context is CONDITIONAL: supply `occupancyGroup` + `spaceType`, or a
-     * `roomType` for them to correlate from, or a mix — an explicit axis always
-     * wins, and an axis that resolves to nothing is a 400 naming it. The full rule,
-     * with the validator's own messages, is on {@link CodeContextRequest}.
-     *
-     * Read `summary.status` honestly: `unverified` means no comparable rating is on
-     * file. It is not a pass, and it is common. Use {@link CodesClient.requirements}
-     * when you have no candidates yet, and `mg.materialBlocks()` to see whether a
-     * material's fire/slip facts are missing or merely unverified.
-     *
-     * 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

@@ -1,99 +0,0 @@
-export class CodesClient {
-    #transport;
-    constructor(transport) {
-        this.#transport = transport;
-    }
-    /**
-     * THE QUESTION: "what may I even say about a space?" — the vocabulary for
-     * stating a code context, and the first call of the three.
-     *
-     * Everything {@link CodesClient.requirements} and {@link CodesClient.advisory}
-     * accept is listed here, so nothing need be hardcoded and a 400 for an unknown
-     * jurisdiction / occupancy / space is always avoidable.
-     *
-     * 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 `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);
-     */
-    async context(signal) {
-        return await this.#transport.get("list_code_context", undefined, signal);
-    }
-    /**
-     * THE QUESTION: "what does this space DEMAND?" — before any candidate exists.
-     *
-     * Run it before shortlisting, not after: it tells you which specification to
-     * filter on, which you then spend on `mg.bySpec()` or `mg.search({ filters })`.
-     * Use {@link CodesClient.advisory} once you hold candidates to badge.
-     *
-     * 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})`);
-     */
-    async requirements(input, signal) {
-        return await this.#transport.get("list_code_requirements", {
-            jurisdiction: input.jurisdictionId,
-            occupancy: input.occupancyGroup,
-            room: input.roomType,
-            space: input.spaceType,
-            sprinklered: input.sprinklered,
-        }, signal);
-    }
-    /**
-     * THE QUESTION: "do THESE candidates satisfy what this space demands?" — the
-     * third call, once you hold materials.
-     *
-     * Context is CONDITIONAL: supply `occupancyGroup` + `spaceType`, or a
-     * `roomType` for them to correlate from, or a mix — an explicit axis always
-     * wins, and an axis that resolves to nothing is a 400 naming it. The full rule,
-     * with the validator's own messages, is on {@link CodeContextRequest}.
-     *
-     * Read `summary.status` honestly: `unverified` means no comparable rating is on
-     * file. It is not a pass, and it is common. Use {@link CodesClient.requirements}
-     * when you have no candidates yet, and `mg.materialBlocks()` to see whether a
-     * material's fire/slip facts are missing or merely unverified.
-     *
-     * 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");
-     */
-    async advisory(input, signal) {
-        return await this.#transport.post("resolveCodeAdvisory", input, signal);
-    }
-}