@instruments/materialgraph 0.25.0 → 0.27.0

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/citation-types.d.ts

@@ -1,10 +1,10 @@
 /** Small handle carried by a verdict cell. Resolve it only when evidence is opened. */
-export interface VerdictCitation {
+export type VerdictCitation = {
     citationId: string;
     sourceType: string;
     count: number;
-}
-export interface ResolvedVerdictCitation {
+};
+export type ResolvedVerdictCitation = {
     citationId: string;
     sourceType: string;
     source: {
@@ -31,4 +31,4 @@ export interface ResolvedVerdictCitation {
             };
         };
     };
-}
+};

package/client-config.d.ts

@@ -1,17 +1,15 @@
 /**
- * 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 interface MaterialGraphClientOptions {
+export type MaterialGraphClientOptions = {
     /** A `mg_read_*` API key, presented as `Authorization: Bearer <key>`. */
     apiKey: string;
     /** Override the API origin. Defaults to {@link DEFAULT_BASE_URL}. */
     baseUrl?: string;
     /** Inject a custom `fetch` (tests, proxies). Defaults to the global `fetch`. */
     fetch?: typeof fetch;
-}
+};

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-source-material-comments.d.ts

@@ -29,9 +29,9 @@
  * namespace over a batch's files to rebuild what that read returns. Reach for
  * `list` when you are watching a single file.
  */
-import { HttpTransport } from "./http-transport.js";
+import type { HttpTransport } from "./http-transport.js";
 import type { PostSourceMaterialCommentInput, PostSourceMaterialCommentResult, SourceMaterialCommentThread } from "./run-types.js";
-export interface SourceMaterialCommentsNamespace {
+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
@@ -46,6 +46,6 @@ export interface SourceMaterialCommentsNamespace {
      * 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 function createSourceMaterialCommentsNamespace(transport: HttpTransport): SourceMaterialCommentsNamespace;
+export declare const createSourceMaterialCommentsNamespace: (transport: HttpTransport) => SourceMaterialCommentsNamespace;

package/client-source-material-comments.js

@@ -1,40 +1,6 @@
-/**
- * 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 { HttpTransport } from "./http-transport.js";
 import { listSourceMaterialComments, postSourceMaterialComment, } from "./runs.js";
 /** Bind the comment operations to the client's shared transport. */
-export function createSourceMaterialCommentsNamespace(transport) {
-    return {
-        list: (batchId, sourceId, signal) => listSourceMaterialComments(transport, batchId, sourceId, signal),
-        post: (batchId, sourceId, input, signal) => postSourceMaterialComment(transport, batchId, sourceId, input, signal),
-    };
-}
+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/client-vocabulary.d.ts

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

package/client-vocabulary.js

@@ -1,32 +1,24 @@
-import { HttpTransport } from "./http-transport.js";
 import { resolveOperation } from "./operations.js";
 import { suggestQuery } from "./suggest-types.js";
-export function colourFacets(transport, signal) {
-    return transport.requestJson(resolveOperation("get_colour_facets"), { signal });
-}
-export function resolveColour(transport, name, signal, options) {
-    return transport.requestJson(resolveOperation("resolve_colour_name"), { query: { name, corpusScope: options?.corpusScope }, signal });
-}
-export function suggestColour(transport, q, options, signal) {
-    return transport.requestJson(resolveOperation("suggest_colour_names"), { query: { q, limit: options?.limit }, signal });
-}
-export function suggest(transport, q, options, signal) {
-    return transport.requestJson(resolveOperation("search_suggest"), { query: suggestQuery(q, options), signal });
-}
-export function resolveAttribute(transport, q, options, signal) {
-    return transport.requestJson(resolveOperation("catalog_resolve_attribute"), {
-        query: {
-            q,
-            limit: options?.limit,
-            facetableOnly: options?.facetableOnly,
-        },
-        signal,
-    });
-}
-export function resolveAttributeValue(transport, attributeId, query, options, signal) {
-    return transport.requestJson(resolveOperation("catalog_resolve_value"), {
-        query: { q: query, limit: options?.limit },
-        pathParams: { attributeId },
-        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,
+});
+/**
+ * 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: {
+        blockIds: commaList(options?.blockIds),
+        categoryIds: commaList(options?.categoryIds),
+        cursor: options?.cursor,
+        filterableOnly: options?.filterableOnly,
+        limit: options?.limit,
+        query: options?.query,
+    },
+    signal,
+});