@instruments/materialgraph 0.25.0 → 0.27.0

package/by-spec-types.d.ts

@@ -1,18 +1,5 @@
 import type { ValueResolution } from "./catalog-discovery-types.js";
 import type { VerdictCitation } from "./citation-types.js";
-import type { VariantId } from "./identifiers.js";
-/**
- * One criterion a match satisfied, with the trust behind it.
- *
- * `confidence` (0–1) and `sourceBasis` are the CLAIM's provenance, not decoration
- * — quote them wherever the value is quoted. A `null` on either means the trust
- * is unrecorded, which is weaker than a low number, not stronger.
- */
-export interface BySpecMatchedCell {
-    attributeId: string;
-    confidence: number | null;
-    sourceBasis: string | null;
-}
 /**
  * The six states a verdict cell can report — and what each licenses you to say.
  *
@@ -36,7 +23,7 @@ export type BySpecVerdictState = "matched" | "deviated" | "failed" | "unverified
  * Hand-mirrors the `AttributeVerdict` contract from `@materialgraph/contracts`;
  * the OpenAPI `CatalogBySpecResponse` schema is the source of truth on the wire.
  */
-export interface BySpecVerdictCell {
+export type BySpecVerdictCell = {
     attributeId: string;
     state: BySpecVerdictState;
     strength: "required" | "preferred";
@@ -73,7 +60,7 @@ export interface BySpecVerdictCell {
      */
     trustGap: "below_confidence" | "basis_unmet" | "proposed" | null;
     citation?: VerdictCitation;
-}
+};
 /**
  * A match's full report card: every cell, the rolled-up grade, weakest confidence.
  *
@@ -86,30 +73,17 @@ export interface BySpecVerdictCell {
  * `minConfidence` is the WEAKEST cell's confidence — the honest ceiling on the
  * whole card, not an average. Quote it alongside the grade.
  */
-export interface BySpecVerdict {
+export type BySpecVerdict = {
     cells: BySpecVerdictCell[];
     grade: "meets_all" | "close" | "hard_no";
     minConfidence: number | null;
-}
+};
 /**
  * The verdict a materials-search hit carries (MG-625). It IS the shared
  * {@link BySpecVerdict} shape — the single CandidateVerdict mirror — aliased here
  * so search-surface code can name it for what it is rather than duplicating it.
  */
 export type MaterialVerdict = BySpecVerdict;
-export interface BySpecMatch {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    variant: string;
-    color: string | null;
-    imageUrl: string | null;
-    hex: string | null;
-    matched: BySpecMatchedCell[];
-    minConfidence: number | null;
-    verdict: BySpecVerdict;
-}
 /**
  * One criterion the server could not resolve to canonical vocabulary, with the
  * resolver's ranked suggestions for it.
@@ -128,7 +102,7 @@ export interface BySpecMatch {
  * EVERY miss is reported, not just the first, so one round trip is enough to fix
  * a whole spec.
  */
-export interface BySpecUnresolvedCriterion {
+export type BySpecUnresolvedCriterion = {
     /** The parsed attribute id, after the route's surrounding-whitespace trim. */
     attributeId: string;
     /** The parsed value — never overwritten by the attribute id when that id is unknown. */
@@ -137,45 +111,4 @@ export interface BySpecUnresolvedCriterion {
     reason?: "unknown_attribute_or_term" | "not_a_specification";
     /** Ranked candidates for whichever half failed. See {@link ValueResolution}. */
     resolution: ValueResolution;
-}
-/**
- * The find-by-spec envelope — A PAGE, AND NOTHING BUT A PAGE.
- *
- * Read `totalMatches` carefully: despite the name it is the route's own words,
- * "Size of the returned (limited) sample, not the true corpus total" — it is
- * literally `matches.length` under the `limit` you asked for. This surface
- * states NO corpus total, so "N materials meet this specification" is not a
- * claim you can make from one response. Raise `limit`, or say "at least N".
- * `brandsSpanned` is likewise the brand count OF THIS SAMPLE.
- *
- * And check `unresolvedCriteria` BEFORE reading any of that: when it is present
- * the numbers beside it describe a query that never ran.
- */
-export interface BySpecResponse {
-    /** The criteria as parsed — check them before trusting a surprising result. */
-    criteria: Array<{
-        attribute: string;
-        value: string;
-    }>;
-    /** `matches.length`, i.e. THIS SAMPLE under `limit`. Never a corpus total. */
-    totalMatches: number;
-    /** Distinct brands in the returned sample — a lower bound on cross-brand reach. */
-    brandsSpanned: number;
-    /** The sample, photo-first, capped by `limit`. */
-    matches: BySpecMatch[];
-    /**
-     * Present ONLY when a criterion failed exact canonical-vocabulary membership —
-     * and its presence means THE QUERY WAS NEVER RUN. A pre-flight gate short-circuits
-     * before the search, so the rest of the envelope is a placeholder rather than
-     * a finding: `matches` is `[]` and `totalMatches` is `0` because nothing was
-     * searched, not because nothing qualifies. Reporting that zero as "no material
-     * meets this specification" states a fact about the corpus on the strength of
-     * a question nobody asked it.
-     *
-     * Treat these criteria as UNAPPLIED and surface them: retry with a
-     * `resolution.candidates` id (subject to `recommendedAction` — `ambiguous`
-     * means ask, not pick), or say the value could not be resolved. Absent means
-     * every criterion resolved and the query did run.
-     */
-    unresolvedCriteria?: BySpecUnresolvedCriterion[];
-}
+};

package/by-spec-types.js

@@ -1,7 +1,9 @@
-// ── Catalog / spec — find-by-spec wire types ─────────────────────────────────
+// ── Catalog / spec: verdict wire types ──────────────────────────────────────
 //
-// Hand-maintained mirror of the `CatalogBySpecResponse` OpenAPI schema (the
-// source of truth on the wire); the `sdk-openapi-parity` test gates this against
-// the generated spec. Split out of `types.ts` to keep that file under its growth
-// baseline; re-exported from `types.ts` so importers see no change.
+// Hand-maintained mirror of the shared CandidateVerdict and of the pre-flight
+// unresolved-criterion contract. The by-spec ROUTE these once described
+// (`catalog_by_spec`) moved to `list_variants`'s `filters` (MG-2222); the
+// verdict and unresolved-criterion shapes below are independent of that route
+// and stay. Split out of `types.ts` to keep that file under its growth
+// baseline; re-exported from `types.ts`.
 export {};

package/catalog-discovery-types.d.ts

@@ -6,16 +6,12 @@
  * then spend on `mg.bySpec()` or `mg.search({ filters })`.
  */
 import type { OpenEnum } from "./types.js";
-/** Options for resolving a free-text value against one attribute's dictionary. */
-export interface ResolveAttributeValueOptions {
-    limit?: number;
-}
 /**
  * One ranked canonical value candidate. `tier` says HOW it matched, strongest
  * first: `exact_id` > `exact_alias` > `lexical` > `semantic`. A `semantic` hit
  * is a guess worth confirming, not an equivalence.
  */
-export interface ResolveValueCandidate {
+export type ResolveValueCandidate = {
     id: string;
     label: string;
     dictionaryId?: string;
@@ -23,11 +19,10 @@ export interface ResolveValueCandidate {
     tier: OpenEnum<"exact_id" | "exact_alias" | "lexical" | "semantic">;
     /** Present only for a colour_family candidate resolved via the colorscope fallback. */
     via?: OpenEnum<"colorscope">;
-}
+};
 /**
  * The resolver's verdict on ONE free-text token — the single shape every
- * resolving surface speaks, so a caller learns to read it once. Returned whole
- * by {@link MaterialGraphClient.resolveAttributeValue}, and carried per bad
+ * resolving surface speaks, so a caller learns to read it once. Carried per bad
  * criterion by `bySpec`'s `unresolvedCriteria`.
  *
  * READ `recommendedAction`, NOT JUST `best`. `ambiguous` with a populated
@@ -45,36 +40,26 @@ export interface ResolveValueCandidate {
  * `query` is the trimmed token that was actually resolved, which is how you tell
  * WHICH half of a failed `attribute:value` pair was the problem.
  */
-export interface ValueResolution {
+export type ValueResolution = {
     status: OpenEnum<"resolved" | "ambiguous" | "unresolved">;
     query: string;
     best: ResolveValueCandidate | null;
     candidates: ResolveValueCandidate[];
     recommendedAction: OpenEnum<"use_best" | "choose_from_candidates" | "ask_user" | "none_found">;
-}
-/** Response from resolving a free-text value against one attribute's dictionary. */
-export interface ResolveAttributeValueResponse {
-    attribute: {
-        id: string;
-        name: string;
-        dictionaryId: string;
-    };
-    /** The verdict on `q`. Read `recommendedAction` — see {@link ValueResolution}. */
-    resolution: ValueResolution;
-}
+};
 /** Options for searching registry attributes and value-dictionary terms together. */
-export interface VocabularySearchOptions {
+export type VocabularySearchOptions = {
     limit?: number;
     kind?: "attribute" | "term";
-}
+};
 /** One ranked cross-vocabulary candidate. */
-export interface VocabularySearchCandidate extends ResolveValueCandidate {
+export type VocabularySearchCandidate = {
     kind: OpenEnum<"attribute" | "term">;
     /** Present for terms: attributes whose value dictionary owns this term. */
     attributeIds?: string[];
-}
+} & ResolveValueCandidate;
 /** Response from the cross-vocabulary catalog search. */
-export interface VocabularySearchResponse {
+export type VocabularySearchResponse = {
     query: string;
     results: VocabularySearchCandidate[];
-}
+};

package/catalogue-client.d.ts

@@ -1,53 +1,34 @@
-import type { BrandMostSampledResponse } from "./brand-most-sampled-types.js";
 import type { CatalogDocumentList, CatalogPageListResult, CatalogProductReferenceReadResult, CatalogueChannelCollectionsResponse, CatalogueCollectionsOptions, CatalogueDocumentAccessResult, CataloguePageRepresentationReadResult, CatalogueReferenceBatchResponse } from "./catalogue-types.js";
-import type { CompareInput, CompareResponse } from "./compare-types.js";
-import type { CreateCorrectionInput, CorrectionResponse, CorrectionsListResponse } from "./correction-types.js";
 import type { HttpTransport } from "./http-transport.js";
 import type { VariantId } from "./identifiers.js";
-import type { IdentifySelectedPageInput, IdentifySelectedPageResult } from "./identify-types.js";
-import type { MatchRejection, MatchRejectionList, RejectMatchResultInput } from "./match-rejection-types.js";
+import type { IdentifyResponse, IdentifyVariantInput } from "./identify-types.js";
 import type { SamplizeCatalogueOptions, SamplizeCataloguePage } from "./samplize-catalogue-types.js";
 import type { SamplizeColorVecCache } from "./samplize-colorvec.js";
 /** Catalogue publication operations inherited by the public SDK client. */
 export declare class CatalogueClient {
     #private;
     protected constructor(transport: HttpTransport);
-    /** Brand products ranked by observed Material Bank sample-order lines, with window provenance. */
-    brandMostSampled(brandId: string, options?: {
-        limit?: number;
-    }, signal?: AbortSignal): Promise<BrandMostSampledResponse>;
-    /** Compare canonical Variants without searching or ranking them. */
-    compare(input: CompareInput, signal?: AbortSignal): Promise<CompareResponse>;
-    /** Submit confirmed caller-authored review work; never changes accepted truth. */
-    createCorrection(input: CreateCorrectionInput, options: {
-        idempotencyKey: string;
-        signal?: AbortSignal;
-    }): Promise<CorrectionResponse>;
-    getCorrection(correctionId: string, signal?: AbortSignal): Promise<CorrectionResponse>;
-    listCorrections(input?: {
-        cursor?: string;
-        limit?: number;
-    }, signal?: AbortSignal): Promise<CorrectionsListResponse>;
     /**
-     * Record "not this" on one result a match showed, against the response it
-     * came from. `responseId` is that response's `attribution.responseId`; the
-     * call needs the same key the match was made with. Repeating a rejection
-     * returns the original receipt. This judges the match ranking and is never a
-     * catalogue correction - wrong product facts go through `createCorrection`.
+     * THE QUESTION: "what does this manufacturer page or code resolve to in the
+     * graph?" Give `input.url` alone, or `input.code` with `input.brandId` (from
+     * {@link CatalogueClient.brands} - inherited by {@link MaterialGraphClient})
+     * when there is no page to read.
+     *
+     * Exact and scoreless: a sibling colourway, a similar image or a brand match
+     * alone never identifies a variant. Read `data.outcome` - `identified` names
+     * an exact stored variant, `placed` an exact brand with no variant match,
+     * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
+     * never a guess. The submitted URL is never persisted.
      */
-    rejectMatchResult(responseId: string, input: RejectMatchResultInput, signal?: AbortSignal): Promise<MatchRejection>;
-    /** Read one match response back with every rejection recorded against it. */
-    matchRejections(responseId: string, signal?: AbortSignal): Promise<MatchRejectionList>;
-    /** Identify the canonical graph subject for one explicitly selected page. */
-    identify(input: IdentifySelectedPageInput, signal?: AbortSignal): Promise<IdentifySelectedPageResult>;
+    identify(input: IdentifyVariantInput, signal?: AbortSignal): Promise<IdentifyResponse>;
     /** Complete producer-owned vectors and classifications for portable colour matching. */
     samplizeColorVecCache(sourceVersion: string, signal?: AbortSignal): Promise<SamplizeColorVecCache>;
     /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */
     samplizeCatalogueSearch(input: {
-        palette?: Array<{
+        palette?: {
             hex: string;
             proportion: number;
-        }>;
+        }[];
         query?: string;
         reference?: string;
         direction?: "similar" | "lighter" | "darker" | "muted";
@@ -73,13 +54,13 @@ export declare class CatalogueClient {
         rankingVersion?: string;
         dictionaryVersion?: string;
         eligibleCount?: number;
-        groups?: Array<{
+        groups?: {
             hex: string;
             proportion: number;
             quota: number;
             ids: string[];
             shortfall: number;
-        }>;
+        }[];
         ids: string[];
         limited: boolean;
         sourceVersion: string;

package/catalogue-client.js

@@ -5,79 +5,44 @@ export class CatalogueClient {
     constructor(transport) {
         this.#transport = transport;
     }
-    /** Brand products ranked by observed Material Bank sample-order lines, with window provenance. */
-    brandMostSampled(brandId, options = {}, signal) {
-        return this.#transport.requestJson(resolveOperation("brands.most_sampled"), { query: { brandId, ...options }, signal });
-    }
-    /** Compare canonical Variants without searching or ranking them. */
-    compare(input, signal) {
-        return this.#transport.requestJson(resolveOperation("retrieval.compare"), {
-            body: input,
-            signal,
-        });
-    }
-    /** Submit confirmed caller-authored review work; never changes accepted truth. */
-    createCorrection(input, options) {
-        if (!/^[\x21-\x7e]{1,200}$/.test(options.idempotencyKey))
-            throw new Error("A valid Idempotency-Key is required for Correction submission.");
-        return this.#transport.requestJson(resolveOperation("corrections.create"), {
-            body: input,
-            ...options,
-        });
-    }
-    getCorrection(correctionId, signal) {
-        return this.#transport.requestJson(resolveOperation("corrections.get"), {
-            pathParams: { correctionId },
-            signal,
-        });
-    }
-    listCorrections(input = {}, signal) {
-        return this.#transport.requestJson(resolveOperation("corrections.list"), {
-            query: input,
-            signal,
-        });
-    }
     /**
-     * Record "not this" on one result a match showed, against the response it
-     * came from. `responseId` is that response's `attribution.responseId`; the
-     * call needs the same key the match was made with. Repeating a rejection
-     * returns the original receipt. This judges the match ranking and is never a
-     * catalogue correction - wrong product facts go through `createCorrection`.
+     * THE QUESTION: "what does this manufacturer page or code resolve to in the
+     * graph?" Give `input.url` alone, or `input.code` with `input.brandId` (from
+     * {@link CatalogueClient.brands} - inherited by {@link MaterialGraphClient})
+     * when there is no page to read.
+     *
+     * Exact and scoreless: a sibling colourway, a similar image or a brand match
+     * alone never identifies a variant. Read `data.outcome` - `identified` names
+     * an exact stored variant, `placed` an exact brand with no variant match,
+     * `ambiguous` carries bounded `candidates`, and `unresolved` states why,
+     * never a guess. The submitted URL is never persisted.
      */
-    rejectMatchResult(responseId, input, signal) {
-        return this.#transport.requestJson(resolveOperation("reject_match_result"), { pathParams: { responseId }, body: input, signal });
-    }
-    /** Read one match response back with every rejection recorded against it. */
-    matchRejections(responseId, signal) {
-        return this.#transport.requestJson(resolveOperation("list_match_rejections"), { pathParams: { responseId }, signal });
-    }
-    /** Identify the canonical graph subject for one explicitly selected page. */
-    identify(input, signal) {
-        return this.#transport.requestJson(resolveOperation("retrieval.identify"), { body: input, signal });
+    async identify(input, signal) {
+        return await this.#transport.requestJson(resolveOperation("retrieval.identify"), { body: input, signal });
     }
     /** Complete producer-owned vectors and classifications for portable colour matching. */
-    samplizeColorVecCache(sourceVersion, signal) {
-        return this.#transport.requestJson(resolveOperation("samplize_colorvec_cache"), { query: { sourceVersion }, signal });
+    async samplizeColorVecCache(sourceVersion, signal) {
+        return await this.#transport.requestJson(resolveOperation("samplize_colorvec_cache"), { query: { sourceVersion }, signal });
     }
     /** MG-owned full-catalogue facets and directional colour refinement before page limiting. */
-    samplizeCatalogueSearch(input, signal) {
-        return this.#transport.requestJson(resolveOperation("samplize_catalogue_search"), { body: input, signal });
+    async samplizeCatalogueSearch(input, signal) {
+        return await this.#transport.requestJson(resolveOperation("samplize_catalogue_search"), { body: input, signal });
     }
     /** Complete version-pinned Samplize paint corpus; stock never limits eligibility. */
-    samplizeCatalogue(options = {}, signal) {
-        return this.#transport.requestJson(resolveOperation("samplize_catalogue_products"), { query: { ...options }, signal });
+    async samplizeCatalogue(options = {}, signal) {
+        return await this.#transport.requestJson(resolveOperation("samplize_catalogue_products"), { query: { ...options }, signal });
     }
     /**
      * Read exact, verified brand-publication page relationships for variants.
      * Missing evidence stays explicit; this operation never guesses a page from
      * a generic PDF.
      */
-    catalogueReferences(input, signal) {
-        return this.#transport.requestJson(resolveOperation("get_catalogue_references_batch"), { body: input, signal });
+    async catalogueReferences(input, signal) {
+        return await this.#transport.requestJson(resolveOperation("get_catalogue_references_batch"), { body: input, signal });
     }
     /** List product collections with governed catalogue-channel membership. */
-    catalogueCollections(options = {}, signal) {
-        return this.#transport.requestJson(resolveOperation("list_catalogue_channel_collections"), {
+    async catalogueCollections(options = {}, signal) {
+        return await this.#transport.requestJson(resolveOperation("list_catalogue_channel_collections"), {
             query: {
                 limit: options.limit,
                 offset: options.offset,
@@ -87,23 +52,23 @@ export class CatalogueClient {
         });
     }
     /** List immutable catalog documents retained from verified source material. */
-    catalogs(signal) {
-        return this.#transport.requestJson(resolveOperation("list_catalog_documents"), { signal });
+    async catalogs(signal) {
+        return await this.#transport.requestJson(resolveOperation("list_catalog_documents"), { signal });
     }
     /** List stable one-based page identities and their representation status. */
-    catalogPages(catalogId, options = {}, signal) {
-        return this.#transport.requestJson(resolveOperation("list_catalog_pages"), { pathParams: { catalogId }, query: options, signal });
+    async catalogPages(catalogId, options = {}, signal) {
+        return await this.#transport.requestJson(resolveOperation("list_catalog_pages"), { pathParams: { catalogId }, query: options, signal });
     }
     /** Read a retained page representation or its exact missing-artifact receipt. */
-    catalogPageRepresentation(pageId, signal) {
-        return this.#transport.requestJson(resolveOperation("get_catalog_page_representation"), { pathParams: { pageId }, signal });
+    async catalogPageRepresentation(pageId, signal) {
+        return await this.#transport.requestJson(resolveOperation("get_catalog_page_representation"), { pathParams: { pageId }, signal });
     }
     /** Read every verified product/page reference for one retained catalog. */
-    catalogReferences(catalogId, signal) {
-        return this.#transport.requestJson(resolveOperation("list_catalog_product_references"), { pathParams: { catalogId }, signal });
+    async catalogReferences(catalogId, signal) {
+        return await this.#transport.requestJson(resolveOperation("list_catalog_product_references"), { pathParams: { catalogId }, signal });
     }
     /** Resolve browser-safe access to one immutable catalogue document. */
-    catalogueDocumentAccess(documentId, signal) {
-        return this.#transport.requestJson(resolveOperation("get_catalogue_document_access"), { pathParams: { documentId }, signal });
+    async catalogueDocumentAccess(documentId, signal) {
+        return await this.#transport.requestJson(resolveOperation("get_catalogue_document_access"), { pathParams: { documentId }, signal });
     }
 }

package/catalogue-types.d.ts

@@ -57,6 +57,43 @@ export interface CatalogueReference {
     status: "verified";
     isPrimary: boolean;
 }
+/**
+ * Why a known variant has no verified reference. None of these says the
+ * product is missing from the printed book; nobody records how many of a
+ * brand's products a publication contains.
+ */
+export type CatalogueReferenceAbsenceReason = 
+/**
+ * The registry retains no publication for the variant's brand. It says
+ * nothing about whether the maker publishes one.
+ */
+"no_publication_on_record"
+/** The edition is known but its document is not retained. */
+ | "publication_source_unavailable"
+/** The document is retained but no page has been reviewed. */
+ | "publication_not_reviewed"
+/** Pages were reviewed and this product is not among the references yet. */
+ | "product_not_yet_referenced";
+/** The brand publication a `no_verified_reference` result was judged against. */
+export type CatalogueReferencePublication = {
+    brand: {
+        id: string;
+        name: string;
+    };
+    catalogue: {
+        id: string;
+        title: string;
+    };
+    /** Null when the edition's document is not retained. */
+    documentId: string | null;
+    edition: {
+        id: string;
+        label: string;
+        title?: string;
+    };
+    /** Reviewed references the publication holds; present only when its pages were reviewed. */
+    referencedProductCount?: number;
+};
 export type CatalogueReferenceResult = {
     variantId: string;
     status: "verified";
@@ -64,6 +101,9 @@ export type CatalogueReferenceResult = {
 } | {
     variantId: string;
     status: "no_verified_reference";
+    reason: CatalogueReferenceAbsenceReason;
+    /** Absent only when `reason` is `no_publication_on_record`. */
+    publication?: CatalogueReferencePublication;
 } | {
     variantId: string;
     status: "unresolved_variant";
@@ -188,10 +228,10 @@ export interface CatalogAvailableReceipt {
         pageCount: number;
     };
     render: {
-        failedPages: Array<{
+        failedPages: {
             documentPage: number;
             reason: string;
-        }>;
+        }[];
         renderedPages: number;
         status: "complete" | "partial" | "not_recorded";
     };
@@ -347,10 +387,10 @@ export type CatalogPageListResult = {
     };
     representationCoverage: {
         available: number;
-        failuresByReason: Array<{
+        failuresByReason: {
             count: number;
             reason: "retained_representation_not_found";
-        }>;
+        }[];
         total: number;
         unavailable: number;
     };

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 });
+    }
+}