@instruments/materialgraph 0.7.0 → 0.8.0

package/runs.d.ts

@@ -1,6 +1,6 @@
 import { HttpTransport } from "./http-transport.js";
 import type { FinishScheduleResponse, GetRunScheduleOptions } from "./schedule-types.js";
-import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
+import { type CapabilityManifestResponse, type CreatePublicRunRequest, type CreatePublicRunResponse, type DrainRunEventsOptions, type ListRunsOptions, type PublicRunListResponse, type PublicRunResponse, type ResumeRunOptions, type RunEvent, type SourceMaterialBatchDetail, type SourceMaterialBatchReceipt, type StreamRunEventsOptions, type UploadSourceMaterialInput } from "./run-types.js";
 /**
  * Upload one atomic source-material batch (`POST /api/v1/source-material`).
  * Accepts the pile-of-files shape (`{ files }` → repeatable `files` field) or
@@ -25,6 +25,20 @@ export declare function getSourceMaterialBatch(transport: HttpTransport, batchId
 export declare function capabilities(transport: HttpTransport, signal?: AbortSignal): Promise<CapabilityManifestResponse>;
 /** Start an asynchronous capability Run (`POST /api/v1/runs`). */
 export declare function createRun(transport: HttpTransport, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
+/**
+ * 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 declare function listRuns(transport: HttpTransport, options?: ListRunsOptions): Promise<PublicRunListResponse>;
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export declare function getRun(transport: HttpTransport, runId: string, signal?: AbortSignal): Promise<PublicRunResponse>;
 /**

package/runs.js

@@ -99,6 +99,30 @@ export function createRun(transport, body, signal) {
         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 } : {}),
+    });
+}
 /** Get a Run's current state (`GET /api/v1/runs/{runId}`). */
 export function getRun(transport, runId, signal) {
     return transport.requestJson(runOperation("get_public_run"), {

package/schema-resource-types.d.ts

@@ -1,20 +1,23 @@
-/**
- * Wire types for the governed STATIC schema (`GET /api/v1/schema/*`).
- *
- * THE LENS: "what does the registry DEFINE?" — blocks, attributes, units, value
- * dictionaries, product types and their external mappings. Definitions, not
- * data: nothing here says how many materials carry an attribute or which values
- * the corpus holds. For that, use `mg.specificationFacets()` and
- * `mg.attributeValues()`; for one term explained in prose, `mg.glossary()`; for
- * what one material has been determined on, `mg.materialBlocks()`.
- *
- * Every id here (`attributeId`, `blockId`, product-type keys) is canonical
- * VOCABULARY, not an opaque token — this is where you discover it rather than
- * invent it.
- */
 import type { OpenEnum } from "./types.js";
 /** The nine governed static resources. */
 export type SchemaResource = "blocks" | "attributes" | "verticals" | "productTypes" | "units" | "valueDictionaries" | "sourceRequirements" | "productTypeTemplates" | "mappings";
+/**
+ * Resource → the operation that serves it. Internal to the SDK (`index.ts`
+ * re-exports this module's TYPES only), and it lives beside
+ * {@link SchemaResource} rather than in the client so the mapping and the union
+ * it must cover cannot drift apart.
+ */
+export declare const SCHEMA_RESOURCE_OPERATION_IDS: {
+    readonly blocks: "list_schema_blocks";
+    readonly attributes: "list_schema_attributes";
+    readonly verticals: "list_schema_verticals";
+    readonly productTypes: "list_schema_product_types";
+    readonly units: "list_schema_units";
+    readonly valueDictionaries: "list_schema_value_dictionaries";
+    readonly sourceRequirements: "list_schema_source_requirements";
+    readonly productTypeTemplates: "list_schema_product_type_templates";
+    readonly mappings: "list_schema_mappings";
+};
 export type SchemaResourceRequest = SchemaResource;
 export interface SchemaLifecycle {
     status: OpenEnum<"draft" | "active" | "deprecated">;

package/schema-resource-types.js

@@ -1 +1,17 @@
-export {};
+/**
+ * Resource → the operation that serves it. Internal to the SDK (`index.ts`
+ * re-exports this module's TYPES only), and it lives beside
+ * {@link SchemaResource} rather than in the client so the mapping and the union
+ * it must cover cannot drift apart.
+ */
+export const SCHEMA_RESOURCE_OPERATION_IDS = {
+    blocks: "list_schema_blocks",
+    attributes: "list_schema_attributes",
+    verticals: "list_schema_verticals",
+    productTypes: "list_schema_product_types",
+    units: "list_schema_units",
+    valueDictionaries: "list_schema_value_dictionaries",
+    sourceRequirements: "list_schema_source_requirements",
+    productTypeTemplates: "list_schema_product_type_templates",
+    mappings: "list_schema_mappings",
+};

package/search-result-validation.js

@@ -143,6 +143,9 @@ export function checkSearchResultItem(value, what, fail) {
     requireString(record.product, `${what}.product`, fail);
     requireNullableString(record.brandSlug, `${what}.brandSlug`, fail);
     requireNullableString(record.productId, `${what}.productId`, fail);
+    // `z.string().optional()` — absent, or a string. NOT nullable: the emit path
+    // omits the key rather than sending null when no MB identity is known.
+    requireOptionalString(record.materialBankId, `${what}.materialBankId`, fail);
     requireNullableString(record.color, `${what}.color`, fail);
     requireNullableString(record.variantName, `${what}.variantName`, fail);
     requireNullableString(record.imageUrl, `${what}.imageUrl`, fail);

package/types.d.ts

@@ -25,6 +25,7 @@
  *     match set. Follow the cursor for the rest, and never report a page size as
  *     a total.
  */
+import type { ByColourSwatch } from "./by-colour-types.js";
 import type { BySpecVerdict } from "./by-spec-types.js";
 import type { Cursor, ProductId, VariantId } from "./identifiers.js";
 import type { MaterialDetail, MaterialTile } from "./material-types.js";
@@ -39,12 +40,22 @@ export type OpenEnum<T extends string> = T | (string & {});
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
-/** One palette swatch of a material's main image. */
+/**
+ * One palette swatch of a material's main image — colour DERIVED FROM PRODUCT
+ * IMAGERY, so read it as visual likeness, never as a declared colour spec.
+ */
 export interface PaletteSwatch {
     hex: string;
     proportion: number;
     /** Stored human colour name for the swatch, when one was extracted. */
     name?: string | null;
+    /**
+     * `hex` in OKLab, derived server-side so you can sort or measure swatches
+     * without converting them yourself. Additive, so optional: the colour lane and
+     * the material record carry it, other surfaces may not, and absent means "not
+     * derived here" — never "achromatic".
+     */
+    oklab?: OklabTriple;
 }
 /** Loose colour metadata for a search result's main image; every field is independently optional. */
 export interface ColourMeta {
@@ -109,6 +120,16 @@ export interface SearchResultItem {
     product: string;
     brandSlug: string | null;
     productId: ProductId | null;
+    /**
+     * The variant's Material Bank SKU — the same `materialBankId` the material
+     * record carries, so a match card can render straight from a result instead of
+     * paying a per-result lookup. Populated on the MATCH lanes (`match()` and
+     * `matchStream()` frames).
+     *
+     * ABSENT means no MB identity is known for the variant — never that the SKU
+     * cannot be ordered. Presence is the orderability tell; absence is silence.
+     */
+    materialBankId?: string;
     color: string | null;
     variantName: string | null;
     imageUrl: string | null;
@@ -248,44 +269,6 @@ export interface MatchResponse {
     droppedAsDuplicateProduct: number;
     note?: string;
 }
-/** Coarse group + fine type of a colour match's primary product type. */
-export interface MatchCategory {
-    group: string | null;
-    type: string | null;
-}
-/**
- * One colour-palette match.
- *
- * `hex`, `distance` and `closeness` are OKLab geometry over colour EXTRACTED
- * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report it as visual
- * likeness ("reads close to this colour"), never as a stated colour
- * specification.
- */
-export interface ByColourMatch {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    distance: number;
-    closeness: number;
-    category: MatchCategory | null;
-    oklab: OklabTriple | null;
-}
-/** The `search/colours` response. */
-export interface ByColourResponse {
-    query: {
-        colours: string[];
-        categories?: string[];
-        oklab?: OklabTriple;
-    };
-    /** `matches.length` — THIS PAGE. Not a corpus total; this surface states none. */
-    count: number;
-    matches: ByColourMatch[];
-}
 /** One item from the pure colour-scalar browse. */
 export interface BrowseResultItem {
     /** Opaque — round-trip verbatim. */
@@ -303,6 +286,17 @@ export interface BrowseResultItem {
         vibrancy: number | null;
     };
     retired?: boolean;
+    /**
+     * The row's own image palette — the FULL stored palette of the SAME image
+     * `imageUrl` serves, uncapped and in stored order, each swatch with `oklab`
+     * (see {@link ByColourSwatch}), so a card can render, sort or group colours
+     * without a second call. A one-swatch palette means the extractor found one
+     * colour (solid-colour materials are genuinely monochrome), not that the list
+     * was trimmed. ABSENT when no palette is on record for that image: absent
+     * means unknown, NOT that the material has no colours. These swatches come
+     * from product imagery, not from the manufacturer.
+     */
+    palette?: ByColourSwatch[];
 }
 /**
  * A single page of the colour browse — the SDK's one genuinely cursor-paginated
@@ -508,6 +502,7 @@ export interface ResolveAttributeResponse {
     candidates: AttributeCandidate[];
 }
 export type * from "./catalog-discovery-types.js";
+export type * from "./resolve-types.js";
 export type * from "./suggest-types.js";
 export type * from "./by-spec-types.js";
 export interface WhoamiResponse {
@@ -626,20 +621,6 @@ export interface SearchGetParams {
     /** Result projection — `"full"` (default) or the lean `"card"` grid form. */
     view?: OpenEnum<"full" | "card">;
 }
-/** Params for `search/colours`. */
-export interface ByColourParams {
-    /** A single hex (with or without `#`). */
-    hex?: string;
-    /** A palette — repeated as one `colour` query entry each. */
-    colour?: string | string[];
-    /** OKLab triple (all-or-none). */
-    l?: number;
-    a?: number;
-    b?: number;
-    /** HARD category filter — display names or taxonomy ids (repeatable). */
-    category?: string | string[];
-    limit?: number;
-}
 /** Params for the pure colour `search/browse` surface. */
 export interface BrowseParams {
     sort: OpenEnum<"light" | "dark" | "vivid" | "muted" | "colourful">;
@@ -650,7 +631,13 @@ export interface BrowseParams {
     cursor?: Cursor;
     /** Page size. */
     limit?: number;
-    /** Comma-separated product-type ids to restrict the browse to. */
+    /**
+     * Comma-separated taxonomy keys to restrict the browse to, at EITHER tier of
+     * `/api/v1/taxonomy/categories`. A GROUP key (`tile_surfaces`) expands to
+     * every product type under it, a TYPE key (`ceramic_porcelain_tile`) stands
+     * for itself, and a mixed list is their deduplicated union. A key in neither
+     * tier is a 400 listing the valid keys — never an empty page.
+     */
     types?: string;
 }
 /** The Material Match request body — exactly one of `imageBase64`, `imageUrl`, `vector`. */
@@ -695,6 +682,7 @@ export interface MaterialsBatchOptions {
 export interface PairingsOptions {
     /** Comma-separated coarse category display names; filters both arms. */
     categories?: string;
+    /** Page size, 1–24 inclusive (default 12). The server rejects (400), not clamps, values outside this range. */
     limit?: number;
     /** Graph-owned order applied within fixed cospec → considered → colour tiers. */
     order?: PairingOrderMode;