@instruments/materialgraph 0.26.0 → 0.27.1

package/categories-client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The category-tree surface, namespaced as `mg.categories` (MG-2226). Replaces
+ * `taxonomy()` / `GET /api/v1/taxonomy/categories`, retired with no shim.
+ *
+ * `list()` pages the tree (roots, one node's children, or a name/meaning
+ * search), and `get(id)` reads one node in full: its place, the names and
+ * phrases that find it, and the canonical taxonomy concepts it relates to.
+ *
+ * A category id is a TREE KEY, never a canonical `product_category` value,
+ * see {@link CategoryItem.id}. `list()` items are lean (id, name, parent,
+ * whether it has children, and how it matched); `get(id)` has the rest. Page
+ * with `pageInfo.nextCursor` as `cursor`, repeating the same `query` and
+ * `parentId`.
+ *
+ * The namespace holds no transport of its own: the client hands it a bound
+ * `get` callback, so auth, rate-limit accounting and error shaping stay in
+ * exactly one place. `mg.browse` and `mg.codes` set the precedent for a
+ * namespace over flat methods.
+ */
+import type { CategoriesGetResult, CategoriesListInput, CategoriesListResult } from "./category-types.js";
+import type { QueryParams } from "./http-transport.js";
+import type { SdkOperationId } from "./operations.js";
+/** The client's own request primitive, handed down so this file owns no transport. */
+export type CategoriesTransport = {
+    get<T>(operationId: SdkOperationId, query?: QueryParams, signal?: AbortSignal, pathParams?: Readonly<Record<string, string>>): Promise<T>;
+};
+export declare class CategoriesClient {
+    #private;
+    constructor(transport: CategoriesTransport);
+    /**
+     * One bounded page of the category tree (GET `/api/v1/categories`). With
+     * nothing set, the top-level categories; `parentId` alone, that category's
+     * direct children; `query`, every category (or only `parentId` and
+     * everything under it) by name, phrase, near spelling or meaning: the
+     * first method that finds anything wins, and every match it finds is
+     * returned, ranked by method then distance.
+     *
+     * An unknown `parentId`, or a cursor from another `query`/`parentId`, is a
+     * 400. No match is a successful empty page, never an error.
+     *
+     * @example
+     * const roots = await mg.categories.list();
+     * const tiles = await mg.categories.list({ parentId: "tile_surfaces" });
+     * const found = await mg.categories.list({ query: "wallpaper" });
+     */
+    list(input?: CategoriesListInput, signal?: AbortSignal): Promise<CategoriesListResult>;
+    /**
+     * One category by id (GET `/api/v1/categories/{id}`): its place in the tree
+     * (ancestors, children), the names and phrases that find it, and the
+     * canonical taxonomy concepts it relates to. `productCategory.concepts[].termId`
+     * is what a record's `product_category` attribute holds; category filters
+     * elsewhere take the id, never that termId.
+     *
+     * An id that names no category is a 404; a canonical `product_category`
+     * termId passed as `id` is a 404 naming it as one, so find the category with
+     * {@link CategoriesClient.list} instead.
+     *
+     * @example
+     * const category = await mg.categories.get("wall_paneling");
+     * category.productCategory.concepts.map((c) => c.termId); // ["wall_panel"]
+     */
+    get(id: string, signal?: AbortSignal): Promise<CategoriesGetResult>;
+}

package/categories-client.js

@@ -0,0 +1,48 @@
+export class CategoriesClient {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /**
+     * One bounded page of the category tree (GET `/api/v1/categories`). With
+     * nothing set, the top-level categories; `parentId` alone, that category's
+     * direct children; `query`, every category (or only `parentId` and
+     * everything under it) by name, phrase, near spelling or meaning: the
+     * first method that finds anything wins, and every match it finds is
+     * returned, ranked by method then distance.
+     *
+     * An unknown `parentId`, or a cursor from another `query`/`parentId`, is a
+     * 400. No match is a successful empty page, never an error.
+     *
+     * @example
+     * const roots = await mg.categories.list();
+     * const tiles = await mg.categories.list({ parentId: "tile_surfaces" });
+     * const found = await mg.categories.list({ query: "wallpaper" });
+     */
+    async list(input = {}, signal) {
+        return await this.#transport.get("list_categories", {
+            cursor: input.cursor,
+            limit: input.limit,
+            parentId: input.parentId,
+            query: input.query,
+        }, signal);
+    }
+    /**
+     * One category by id (GET `/api/v1/categories/{id}`): its place in the tree
+     * (ancestors, children), the names and phrases that find it, and the
+     * canonical taxonomy concepts it relates to. `productCategory.concepts[].termId`
+     * is what a record's `product_category` attribute holds; category filters
+     * elsewhere take the id, never that termId.
+     *
+     * An id that names no category is a 404; a canonical `product_category`
+     * termId passed as `id` is a 404 naming it as one, so find the category with
+     * {@link CategoriesClient.list} instead.
+     *
+     * @example
+     * const category = await mg.categories.get("wall_paneling");
+     * category.productCategory.concepts.map((c) => c.termId); // ["wall_panel"]
+     */
+    async get(id, signal) {
+        return await this.#transport.get("get_category", undefined, signal, { id });
+    }
+}

package/category-types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Hand-mirrored wire types for the category tree surface
+ * (`GET /api/v1/categories` - `list_categories`, `GET /api/v1/categories/{id}` -
+ * `get_category`; MG-2226). Like the rest of the SDK these interfaces have NO
+ * runtime dependency on any `@materialgraph/*` package - they mirror the
+ * `listCategoriesInputSchema` / `listCategoriesResultSchema` /
+ * `getCategoryInputSchema` / `getCategoryResultSchema` Zod contracts the routes
+ * are built from.
+ *
+ * A category id is a TREE KEY (a product-type group or a product type, e.g.
+ * `"tile_surfaces"`), never a canonical `product_category` value (a termId such
+ * as `"wall_panel"`). The two vocabularies look alike and are not
+ * interchangeable, and a termId passed where an id belongs is refused, naming
+ * which it is. `get(id).productCategory` is where a category relates to its
+ * termIds; category filters elsewhere in the SDK take the id, never the termId.
+ */
+import type { OpenEnum } from "./types.js";
+/** A category named by id, as in `ancestors` and `children`. */
+export type CategoryRef = {
+    id: string;
+    name: string;
+};
+export type CategoryKind = OpenEnum<"group" | "product_type">;
+/**
+ * How one item matched a `query`: `exact` (the id or a name), `alias` (a
+ * phrase that names the category), `fuzzy` (a near spelling) or `vector`
+ * (similar meaning, from the served vocabulary embeddings). Earlier methods
+ * are surer; a page holds matches from one method only.
+ */
+export type CategoryMatch = {
+    /** The name, former name or phrase that matched. Null for `vector`, which compares meaning. */
+    matchedText: string | null;
+    method: OpenEnum<"exact" | "alias" | "fuzzy" | "vector">;
+};
+/**
+ * One item on a `categories.list` page: what picks the next call. `get(id)`
+ * has the description, ancestors, children, names and concepts.
+ */
+export type CategoryItem = {
+    /** Whether `categories.list({ parentId: this.id })` lists anything. */
+    hasChildren: boolean;
+    /** A tree key, not a canonical `product_category` value. */
+    id: string;
+    /** Present only when the page answers a `query`. */
+    match?: CategoryMatch;
+    name: string;
+    /** The parent category's id, or null for a top-level category. */
+    parentId: string | null;
+};
+export type CategoriesPageInfo = {
+    /** Pass back as `cursor` with the same `query` and `parentId` for the next page. */
+    nextCursor: string | null;
+    returnedCount: number;
+    totalMatches: number;
+};
+export type CategoriesListInput = {
+    /** `pageInfo.nextCursor` from the previous page, with the same `query` and `parentId`. */
+    cursor?: string;
+    /** Items per page, 1 to 50. Default 20. */
+    limit?: number;
+    /** A category id. Alone, lists its children; with `query`, searches it and everything under it. */
+    parentId?: string;
+    /** A category name or description, e.g. `"wallpaper"` or `"beds"`. */
+    query?: string;
+};
+export type CategoriesListResult = {
+    items: CategoryItem[];
+    /** Present only when the query is refused as a category, and says why. */
+    notice?: string;
+    pageInfo: CategoriesPageInfo;
+};
+/**
+ * One canonical taxonomy concept a category relates to. `termId` is the value
+ * a record's `product_category` attribute holds, not the category id. `match`
+ * is present only for product types: `exact` (the same thing), `close`,
+ * `broad` (the concept contains this type) or `narrow` (the concept is one
+ * kind within this type).
+ */
+export type CategoryConcept = {
+    label: string;
+    match?: OpenEnum<"exact" | "close" | "broad" | "narrow">;
+    termId: string;
+    uri: string;
+};
+export type CategoryProductCategory = {
+    concepts: CategoryConcept[];
+    /**
+     * The `product_category` value a record holds when the category alone
+     * decides it. Null for groups and for `conditional` or `unmapped` types.
+     */
+    recordValue: string | null;
+    /**
+     * `mapped`: the category fixes its canonical concepts. `conditional`: each
+     * record's own data chooses between them. `unmapped`: no canonical concept
+     * fits yet.
+     */
+    status: OpenEnum<"mapped" | "conditional" | "unmapped">;
+};
+export type CategoriesGetResult = {
+    /** Phrases that name this category in a `query`. */
+    aliases: string[];
+    /** The categories above this one, root first. Empty for a top-level category. */
+    ancestors: CategoryRef[];
+    /** The categories directly under this one, by name. */
+    children: CategoryRef[];
+    description: string | null;
+    /** Names this category carried before a rename; they still find it. */
+    formerNames: string[];
+    /** A tree key, not a canonical `product_category` value. */
+    id: string;
+    kind: CategoryKind;
+    name: string;
+    productCategory: CategoryProductCategory;
+};

package/client-config.d.ts

@@ -1,12 +1,10 @@
 /**
- * Construction-time configuration for {@link MaterialGraphClient} and the two
- * published constants callers read off it. Split out of `client.ts` so the
+ * Construction-time configuration for {@link MaterialGraphClient} and the
+ * published constant callers read off it. Split out of `client.ts` so the
  * client file carries lenses rather than setup.
  */
 /** The hosted API origin the client talks to unless `baseUrl` overrides it. */
 export declare const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
-/** The server's per-call ceiling on batch material lookups, enforced client-side. */
-export declare const MAX_BATCH_IDS = 100;
 export type MaterialGraphClientOptions = {
     /** A `mg_read_*` API key, presented as `Authorization: Bearer <key>`. */
     apiKey: string;

package/client-config.js

@@ -1,9 +1,7 @@
 /**
- * Construction-time configuration for {@link MaterialGraphClient} and the two
- * published constants callers read off it. Split out of `client.ts` so the
+ * Construction-time configuration for {@link MaterialGraphClient} and the
+ * published constant callers read off it. Split out of `client.ts` so the
  * client file carries lenses rather than setup.
  */
 /** The hosted API origin the client talks to unless `baseUrl` overrides it. */
 export const DEFAULT_BASE_URL = "https://beta.materialgraph.com";
-/** The server's per-call ceiling on batch material lookups, enforced client-side. */
-export const MAX_BATCH_IDS = 100;

package/client-vocabulary.d.ts

@@ -1,10 +1,8 @@
 import type { HttpTransport } from "./http-transport.js";
-import type { ColourFacetsResponse, ResolveAttributeOptions, ResolveAttributeResponse, ResolveAttributeValueOptions, ResolveAttributeValueResponse, ResolveColourOptions, ResolveColourResponse, SuggestColourResponse, SuggestOptions, SuggestResponse } from "./types.js";
-export declare const colourFacets: (transport: HttpTransport, signal?: AbortSignal) => Promise<ColourFacetsResponse>;
+import type { ListAttributesOptions, ListAttributesResult, ResolveColourOptions, ResolveColourResponse, SuggestColourResponse, SuggestOptions, SuggestResponse } from "./types.js";
 export declare const resolveColour: (transport: HttpTransport, name: string, signal?: AbortSignal, options?: ResolveColourOptions) => Promise<ResolveColourResponse>;
 export declare const suggestColour: (transport: HttpTransport, q: string, options?: {
     limit?: number;
 }, signal?: AbortSignal) => Promise<SuggestColourResponse>;
 export declare const suggest: (transport: HttpTransport, q: string, options?: SuggestOptions, signal?: AbortSignal) => Promise<SuggestResponse>;
-export declare const resolveAttribute: (transport: HttpTransport, q: string, options?: ResolveAttributeOptions, signal?: AbortSignal) => Promise<ResolveAttributeResponse>;
-export declare const resolveAttributeValue: (transport: HttpTransport, attributeId: string, query: string, options?: ResolveAttributeValueOptions, signal?: AbortSignal) => Promise<ResolveAttributeValueResponse>;
+export declare const listAttributes: (transport: HttpTransport, options?: ListAttributesOptions, signal?: AbortSignal) => Promise<ListAttributesResult>;

package/client-vocabulary.js

@@ -1,22 +1,24 @@
 import { resolveOperation } from "./operations.js";
 import { suggestQuery } from "./suggest-types.js";
-export const colourFacets = async (transport, signal) => await transport.requestJson(resolveOperation("get_colour_facets"), { signal });
 export const resolveColour = async (transport, name, signal, options) => await transport.requestJson(resolveOperation("resolve_colour_name"), { query: { corpusScope: options?.corpusScope, name }, signal });
 export const suggestColour = async (transport, q, options, signal) => await transport.requestJson(resolveOperation("suggest_colour_names"), { query: { limit: options?.limit, q }, signal });
 export const suggest = async (transport, q, options, signal) => await transport.requestJson(resolveOperation("search_suggest"), {
     query: suggestQuery(q, options),
     signal,
 });
-export const resolveAttribute = async (transport, q, options, signal) => await transport.requestJson(resolveOperation("catalog_resolve_attribute"), {
+/**
+ * A comma list, or nothing at all for an empty one. `[].join(",")` is `""`, and
+ * an absent parameter is the one honest spelling of "no restriction".
+ */
+const commaList = (values) => values === undefined || values.length === 0 ? undefined : values.join(",");
+export const listAttributes = async (transport, options, signal) => await transport.requestJson(resolveOperation("catalog_list_attributes"), {
     query: {
-        facetableOnly: options?.facetableOnly,
+        blockIds: commaList(options?.blockIds),
+        categoryIds: commaList(options?.categoryIds),
+        cursor: options?.cursor,
+        filterableOnly: options?.filterableOnly,
         limit: options?.limit,
-        q,
+        query: options?.query,
     },
     signal,
 });
-export const resolveAttributeValue = async (transport, attributeId, query, options, signal) => await transport.requestJson(resolveOperation("catalog_resolve_value"), {
-    pathParams: { attributeId },
-    query: { limit: options?.limit, q: query },
-    signal,
-});