@instruments/materialgraph 0.25.0 → 0.27.0

package/runs.js

@@ -1,72 +1,76 @@
 /**
  * The Run + source-material namespace — the agentic half of the SDK. These
  * functions take the shared {@link HttpTransport} and speak the hosted Run
- * lifecycle: upload source material, list capabilities, create/read/resume/
- * cancel Runs, and stream (or drain) their events. Box's proxy routes are thin
- * wrappers over exactly these calls.
+ * lifecycle: upload source material, create/read Runs, and stream (or drain)
+ * their events. Box's proxy routes are thin wrappers over exactly these calls.
  */
 import { MaterialGraphError } from "./errors.js";
-import { HttpTransport } from "./http-transport.js";
-import { findSdkOperation, operationPath, } from "./operations.js";
-import { TERMINAL_RUN_EVENT_TYPES, } from "./run-types.js";
+import { findSdkOperation, operationPath } from "./operations.js";
+import { TERMINAL_RUN_EVENT_TYPES } from "./run-types.js";
 import { checkPostSourceMaterialCommentResult, checkSourceMaterialBatchDetail, checkSourceMaterialCommentThread, } from "./source-material-validation.js";
 import { readSseFrames } from "./sse.js";
-function runOperation(operationId) {
+const runOperation = (operationId) => {
     const match = findSdkOperation(operationId);
-    if (!match)
+    if (!match) {
         throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
+    }
     return match;
-}
+};
 /** Build a `Blob` from raw bytes, normalising to an ArrayBuffer-backed view. */
-function bytesToBlob(input) {
+const bytesToBlob = (input) => {
     const type = input.contentType ? { type: input.contentType } : {};
-    if (input.data instanceof ArrayBuffer)
+    if (input.data instanceof ArrayBuffer) {
         return new Blob([input.data], type);
+    }
     // A Uint8Array may be SharedArrayBuffer-backed; copy into a fresh view so the
     // Blob part is unambiguously ArrayBuffer-backed (no cast needed).
     const copy = new Uint8Array(input.data.byteLength);
     copy.set(input.data);
     return new Blob([copy], type);
-}
+};
 /** Append one file to the multipart body, from either input form. */
-function appendFile(form, field, input) {
+const appendFile = (form, field, input) => {
     if (input instanceof Blob) {
-        if (input instanceof File)
+        if (input instanceof File) {
             form.append(field, input, input.name);
-        else
+        }
+        else {
             form.append(field, input);
+        }
         return;
     }
     form.append(field, bytesToBlob(input), input.filename);
-}
+};
 /**
  * Upload one atomic source-material batch (`POST /api/v1/source-material`).
  * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
  * the legacy `{ brief, references }` shape (→ `brief` + repeatable `references`
  * fields). Both wire to multipart the server accepts.
  */
-export async function uploadSourceMaterial(transport, input, signal) {
+export const uploadSourceMaterial = async (transport, input, signal) => {
     const form = new FormData();
     if ("files" in input) {
-        for (const file of input.files)
+        for (const file of input.files) {
             appendFile(form, "files", file);
+        }
     }
     else {
         appendFile(form, "brief", input.brief);
-        for (const reference of input.references ?? [])
+        for (const reference of input.references ?? []) {
             appendFile(form, "references", reference);
+        }
     }
     const url = transport.buildUrl(operationPath(runOperation("upload_source_material")));
     // No Content-Type header: fetch sets multipart/form-data with the boundary.
     const { parsed } = await transport.send({
-        method: "POST",
-        url,
-        headers: transport.authHeaders(),
         body: form,
+        headers: transport.authHeaders(),
+        method: "POST",
         signal,
+        url,
     });
     return parsed;
-}
+};
 /**
  * Read back one uploaded batch (`GET /api/v1/source-material/{batchId}`): every
  * file with a fetchable `url`, and every analysis computed over its bytes
@@ -79,13 +83,13 @@ export async function uploadSourceMaterial(transport, input, signal) {
  * the server's Zod contract so a malformed response fails here with a path into
  * the payload rather than as an undefined three frames away in caller code.
  */
-export async function getSourceMaterialBatch(transport, batchId, signal) {
+export const getSourceMaterialBatch = async (transport, batchId, signal) => {
     const body = await transport.requestJson(runOperation("get_source_material_batch"), {
         pathParams: { batchId },
         signal,
     });
     return checkSourceMaterialBatchDetail(body, batchId);
-}
+};
 /**
  * Read one file's comment thread
  * (`GET /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
@@ -103,13 +107,13 @@ export async function getSourceMaterialBatch(transport, batchId, signal) {
  * 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.
  */
-export async function listSourceMaterialComments(transport, batchId, sourceId, signal) {
+export const listSourceMaterialComments = async (transport, batchId, sourceId, signal) => {
     const body = await transport.requestJson(runOperation("list_source_material_comments"), {
         pathParams: { batchId, sourceId },
         signal,
     });
     return checkSourceMaterialCommentThread(body, sourceId);
-}
+};
 /**
  * Add one remark to a file's thread
  * (`POST /api/v1/source-material/{batchId}/sources/{sourceId}/comments`).
@@ -125,7 +129,7 @@ export async function listSourceMaterialComments(transport, batchId, sourceId, s
  * The result is discriminated on `kind`: switch on it rather than reaching for
  * `replies`, which a `reply` does not have.
  */
-export async function postSourceMaterialComment(transport, batchId, sourceId, input, signal) {
+export const postSourceMaterialComment = async (transport, batchId, sourceId, input, signal) => {
     const body = await transport.requestJson(runOperation("post_source_material_comment"), {
         // Built key by key rather than spread: `parentCommentId` and
         // `idempotencyKey` are forwarded only when PRESENT, so a caller that
@@ -145,122 +149,22 @@ export async function postSourceMaterialComment(transport, batchId, sourceId, in
         signal,
     });
     return checkPostSourceMaterialCommentResult(body, sourceId);
-}
-/** List invocable agents, workflows, and tools (`GET /api/v1/capabilities`). */
-export function capabilities(transport, signal) {
-    return transport.requestJson(runOperation("list_public_capabilities"), {
-        signal,
-    });
-}
+};
 /** Start an asynchronous capability Run (`POST /api/v1/runs`). */
-export function createRun(transport, body, signal) {
-    return transport.requestJson(runOperation("create_public_run"), {
-        body,
-        signal,
-    });
-}
-/**
- * List your own Runs, newest first (`GET /api/v1/runs`).
- *
- * The recovery path for a client that still holds its API key but has lost a Run
- * id — a reinstalled app, or a crash before the id from {@link createRun} was
- * persisted. `{ status: "suspended" }` finds the Run still waiting on an answer.
- *
- * Only the calling principal's own Runs are ever returned; there is no
- * cross-principal listing.
- *
- * Page by following `nextCursor` until it is ABSENT — a full page is not the
- * signal to stop, and an absent cursor is the only one.
- */
-export function listRuns(transport, options = {}) {
-    const query = {
-        ...(options.status === undefined ? {} : { status: options.status }),
-        ...(options.limit === undefined ? {} : { limit: options.limit }),
-        ...(options.cursor === undefined ? {} : { cursor: options.cursor }),
-    };
-    return transport.requestJson(runOperation("list_public_runs"), {
-        ...(Object.keys(query).length > 0 ? { query } : {}),
-        ...(options.signal ? { signal: options.signal } : {}),
-    });
-}
+export const createRun = async (transport, body, signal) => await transport.requestJson(runOperation("create_public_run"), {
+    body,
+    signal,
+});
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
-export function getRun(transport, runId, signal) {
-    return transport.requestJson(runOperation("get_public_run"), {
-        pathParams: { 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`).
- *
- * The `.xlsx` form of the same export is deliberately NOT an SDK method: this
- * transport parses every response as text/JSON and has no binary read path, so
- * a bytes-returning method would mean a second transport surface for one file.
- * Fetch `GET /api/v1/runs/{runId}/schedule.xlsx` directly with the same bearer
- * key when you want the workbook.
- */
-export function getRunSchedule(transport, runId, options = {}) {
-    return transport.requestJson(runOperation("get_run_finish_schedule"), {
-        pathParams: { runId },
-        ...(options.schemeId ? { query: { schemeId: options.schemeId } } : {}),
-        ...(options.signal ? { signal: options.signal } : {}),
-    });
-}
-/**
- * Normalise `resumeRun`'s overloaded third argument.
- *
- * A bare `AbortSignal` stays supported because it is the published shape:
- * reordering that parameter would break any consumer passing it positionally,
- * and this ships with no version bump.
- *
- * Discriminated on `instanceof AbortSignal`, NOT on the presence of `stepId`.
- * `{ signal }` with no `stepId` is a perfectly valid options object, and a
- * key-presence test would misread it as a signal and silently drop the abort.
- */
-function resumeOptions(value) {
-    if (value === undefined)
-        return {};
-    return value instanceof AbortSignal ? { signal: value } : value;
-}
-/**
- * Resume a suspended Run (`POST /api/v1/runs/{runId}/resume`).
- *
- * The third argument takes either an `AbortSignal` (legacy) or
- * {@link ResumeRunOptions}.
- *
- * `stepId` is forwarded whenever it is PRESENT — `!== undefined`, not truthy.
- * An empty string is a present-but-malformed value and must reach the server
- * so its schema rejects it; treating it as absent would silently downgrade a
- * guarded resume into an unguarded one, which is the exact failure this guard
- * exists to prevent.
- *
- * Omitting it sends a body byte-identical to what this sent before. Note the
- * wire cannot distinguish `{ stepId: undefined }` from no key at all —
- * `JSON.stringify` drops both — so the distinction here is construction
- * intent, kept so the serialised body is provably unchanged for old callers.
- */
-export function resumeRun(transport, runId, resumeData, signalOrOptions) {
-    const { stepId, signal } = resumeOptions(signalOrOptions);
-    return transport.requestJson(runOperation("resume_public_run"), {
-        body: { resumeData, ...(stepId !== undefined ? { stepId } : {}) },
-        pathParams: { runId },
-        signal,
-    });
-}
-/** Request durable Run cancellation (`POST /api/v1/runs/{runId}/cancel`). */
-export function cancelRun(transport, runId, signal) {
-    return transport.requestJson(runOperation("cancel_public_run"), {
-        body: {},
-        pathParams: { runId },
-        signal,
-    });
-}
+export const getRun = async (transport, runId, signal) => await transport.requestJson(runOperation("get_public_run"), {
+    pathParams: { runId },
+    signal,
+});
 /** Decode one SSE `data:` frame into a {@link RunEvent}, or `null` when unusable. */
-function decodeRunEvent(data) {
-    if (data.length === 0)
+const decodeRunEvent = (data) => {
+    if (data.length === 0) {
         return null;
+    }
     let parsed;
     try {
         parsed = JSON.parse(data);
@@ -268,13 +172,15 @@ function decodeRunEvent(data) {
     catch (cause) {
         throw MaterialGraphError.unexpected(`MaterialGraph run-event stream sent an unparseable data frame: ${String(cause)}`);
     }
-    if (typeof parsed !== "object" || parsed === null)
+    if (typeof parsed !== "object" || parsed === null) {
         return null;
+    }
     const record = parsed;
-    if (typeof record.sequence !== "number" || typeof record.type !== "string")
+    if (typeof record.sequence !== "number" || typeof record.type !== "string") {
         return null;
+    }
     return parsed;
-}
+};
 /**
  * Stream ordered Run events as an async iterator (`GET
  * /api/v1/runs/{runId}/events`, SSE). Iterates until the stream ends or
@@ -293,8 +199,9 @@ export async function* streamRunEvents(transport, runId, options = {}) {
     });
     for await (const frame of readSseFrames(body, options.signal)) {
         const event = decodeRunEvent(frame.data);
-        if (event)
+        if (event) {
             yield event;
+        }
     }
 }
 /**
@@ -312,30 +219,34 @@ export async function* streamRunEvents(transport, runId, options = {}) {
  * failure (a real 4xx/5xx or transport error) still propagates, keeping the
  * fail-fast surface for genuine upstream problems.
  */
-export async function drainRunEvents(transport, runId, options) {
+export const drainRunEvents = async (transport, runId, options) => {
     const collected = [];
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), options.deadlineMs);
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, options.deadlineMs);
     try {
         for await (const event of streamRunEvents(transport, runId, {
             after: options.after,
             signal: controller.signal,
         })) {
             collected.push(event);
-            if (TERMINAL_RUN_EVENT_TYPES.has(event.type))
+            if (TERMINAL_RUN_EVENT_TYPES.has(event.type)) {
                 break;
+            }
         }
     }
     catch (error) {
         const causedByDeadline = controller.signal.aborted &&
             error instanceof MaterialGraphError &&
             error.kind === "aborted";
-        if (!causedByDeadline)
+        if (!causedByDeadline) {
             throw error;
+        }
     }
     finally {
         clearTimeout(timer);
         controller.abort();
     }
     return collected;
-}
+};

package/samplize-catalogue-types.d.ts

@@ -1,4 +1,4 @@
-export interface SamplizeCatalogueOptions {
+export type SamplizeCatalogueOptions = {
     limit?: number;
     /** Continue with unchanged filters and sourceVersion; omit when filters change. */
     after?: string;
@@ -8,8 +8,8 @@ export interface SamplizeCatalogueOptions {
     collectionHandle?: string;
     /** Pin every subsequent page to the version returned by the first page. */
     sourceVersion?: string;
-}
-export interface SamplizeCatalogueProduct {
+};
+export type SamplizeCatalogueProduct = {
     variantId: string;
     productId: string;
     name: string;
@@ -38,18 +38,18 @@ export interface SamplizeCatalogueProduct {
     };
     sourceProductId: string;
     url: string;
-    sizeVariants: Array<{
+    sizeVariants: {
         sourceVariantId: string;
         sku: string | null;
         title: string | null;
         price: number | null;
         inventoryAvailable: boolean;
         demand: SamplizeDemand | null;
-    }>;
+    }[];
     publishedHexes: SamplizeHexObservation[];
     hexObservations: SamplizeHexObservation[];
-}
-export interface SamplizeCataloguePage {
+};
+export type SamplizeCataloguePage = {
     schemaVersion: 2;
     corpusScope: "samplizeCatalogue";
     sourceVersion: string;
@@ -60,8 +60,8 @@ export interface SamplizeCataloguePage {
     nextCursor: string | null;
     /** True on the final page; completeness requires collecting total unique IDs. */
     complete: boolean;
-}
-export interface SamplizeHexObservation {
+};
+export type SamplizeHexObservation = {
     hex: string;
     publisher: string;
     source: string;
@@ -69,30 +69,30 @@ export interface SamplizeHexObservation {
     sourceBasis: string;
     observedAt: string | null;
     differsFromSelected: boolean;
-}
-export interface SamplizePublicationSource {
+};
+export type SamplizePublicationSource = {
     publisher: "Samplize";
     source: "algolia_shopify_products";
     sourceUrl: string;
     observedAt: string | null;
-}
-export interface SamplizeLrvObservation extends SamplizePublicationSource {
+};
+export type SamplizeLrvObservation = {
     field: string;
     value: number;
-}
-export interface SamplizeDemand extends SamplizePublicationSource {
+} & SamplizePublicationSource;
+export type SamplizeDemand = {
     field: "recently_ordered_count";
     sourceVariantId: string;
     grain: "shopify_variant";
     recentlyOrderedCount: number;
     /** The publisher does not supply the time window. */
     window: null;
-}
-export interface SamplizeCollectionMembership {
+} & SamplizePublicationSource;
+export type SamplizeCollectionMembership = {
     sourceCollectionId: string;
     handle: string;
     url: string;
     publisher: "Samplize";
     source: "algolia_shopify_products";
     observedAt: string | null;
-}
+};

package/samplize-colorvec.d.ts

@@ -1,6 +1,6 @@
 export declare const SAMPLIZE_COLORVEC_RANKING_VERSION = "solid-colorvec-cosine-v2";
 export declare const SAMPLIZE_COLORVEC_EMBEDDING_VERSION = "oklch-anchor-quantiles-v12";
-export interface SamplizeColorVecPaint {
+export type SamplizeColorVecPaint = {
     variantId: string;
     hex: string;
     brand: string;
@@ -13,22 +13,22 @@ export interface SamplizeColorVecPaint {
     lightness: string;
     intensity: string;
     vector: number[] | string;
-}
-export interface SamplizeColorVecCache {
+};
+export type SamplizeColorVecCache = {
     sourceVersion: string;
     dictionaryVersion: string;
     embeddingVersion: string;
     rankingVersion: string;
     generatedAt: string;
     paints: SamplizeColorVecPaint[];
-}
-export interface SamplizeColorVecInput {
+};
+export type SamplizeColorVecInput = {
     hex?: string;
     reference?: string;
-    palette?: Array<{
+    palette?: {
         hex: string;
         proportion: number;
-    }>;
+    }[];
     direction?: "similar" | "lighter" | "darker" | "muted";
     brand?: string[];
     family?: string[];
@@ -39,32 +39,32 @@ export interface SamplizeColorVecInput {
     temperatureMin?: number;
     temperatureMax?: number;
     limit?: number;
-}
+};
 export declare const samplizeSolidColorVector: (hex: string) => number[];
 /** Canonical constraints are shared by full-cache similarity and constrained text retrieval. */
-export declare function selectSamplizeEligiblePaints<T extends Omit<SamplizeColorVecPaint, "vector">>(paints: T[], input: SamplizeColorVecInput): {
-    reference: T | undefined;
-    eligible: T[];
+export declare const selectSamplizeEligiblePaints: <T extends Omit<SamplizeColorVecPaint, "vector">>(paints: T[], input: SamplizeColorVecInput) => {
     counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
+    eligible: T[];
+    reference: T | undefined;
 };
 /** Official portable MG ranking over its complete versioned sampling-channel projection. */
-export declare function createSamplizeColorVecIndex(cache: SamplizeColorVecCache): {
+export declare const createSamplizeColorVecIndex: (cache: SamplizeColorVecCache) => {
     search(input: SamplizeColorVecInput): {
-        ids: string[];
+        countBasis: "complete-catalogue";
+        counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
+        dictionaryVersion: string;
+        eligibleCount: number;
+        embeddingVersion: string;
         groups: {
             hex: string;
+            ids: string[];
             proportion: number;
             quota: number;
-            ids: string[];
             shortfall: number;
         }[];
+        ids: string[];
         limited: boolean;
-        eligibleCount: number;
-        counts: Record<"brand" | "family" | "intensity" | "lightness", Record<string, number>>;
-        sourceVersion: string;
-        dictionaryVersion: string;
-        embeddingVersion: string;
         rankingVersion: string;
-        countBasis: "complete-catalogue";
+        sourceVersion: string;
     };
 };