@instruments/materialgraph 0.29.0 → 0.31.0

package/colour-aggregate-types.d.ts

@@ -1,163 +0,0 @@
-/**
- * Wire types for the colour AGGREGATE surface — `GET /api/v1/colours/profiles`
- * and `GET /api/v1/colours/stats`.
- *
- * Kept out of `types.ts` for the same reason `material-types.ts` and
- * `codes-types.ts` are: the shared mirror is at its source-size budget. Same
- * tolerant-parsing contract as the rest of the mirror — response enums are
- * widened so a new server value still type-checks.
- */
-import type { OpenEnum } from "./types.js";
-/**
- * Which taxonomy tier a colour profile's `categoryKey` names — or `"merged"`,
- * where the key is a composite over a caller-defined key set rather than a
- * taxonomy node.
- */
-export type CategoryTier = OpenEnum<"group" | "type" | "merged">;
-/** How the endpoint picks which colours to keep. */
-export type ColourProfileSelect = OpenEnum<"frequency" | "diverse">;
-/** One representative colour bucket of a category. */
-export type CategoryColour = {
-    hex: string;
-    oklab: {
-        l: number;
-        a: number;
-        b: number;
-    };
-    variantCount: number;
-    /** This bucket's share of the category's coloured variants, 0–1. */
-    proportion: number;
-};
-export type CategoryColourProfile = {
-    categoryKey: string;
-    level: CategoryTier;
-    name: string;
-    path: string;
-    /**
-     * Under `groupBy: "merged"`, the requested keys in composite-key order, so
-     * `categoryKey` never has to be split. Absent on a single-category profile.
-     */
-    members?: string[];
-    variantCount: number;
-    avgLightness: number;
-    avgChroma: number;
-    colours: CategoryColour[];
-};
-/**
- * The snapshot a profile response was computed from. Compare `variantCount`
- * against `colours/stats`' `corpus.withColour` to see how complete the
- * underlying materialized view currently is, and `refreshedAt` for its age.
- */
-export type CategoryColourProfilesBasis = {
-    variantCount: number;
-    refreshedAt: string | null;
-};
-export type CategoryColourProfilesResponse = {
-    profiles: CategoryColourProfile[];
-    basis: CategoryColourProfilesBasis;
-};
-/** Request parameters for `colours.profiles()`. */
-export type ColourProfilesParams = {
-    /** 1–8 category keys, at the tier named by `groupBy`. */
-    productTypeIds: readonly string[];
-    /**
-     * `"group"` merges each group's leaf product types into one palette;
-     * `"merged"` merges EVERY key's leaves into a single combined palette.
-     */
-    groupBy?: "group" | "type" | "merged";
-    /** Representative colours per category, 1–64. */
-    topN?: number;
-    /** `"diverse"` maximises visual distinctness instead of frequency. */
-    select?: "frequency" | "diverse";
-};
-export type ColourStatsCorpus = {
-    variants: number;
-    withColour: number;
-    /** `withColour / variants`, 0–1. */
-    coverage: number;
-};
-export type ColourStatsFamily = {
-    id: string;
-    label: string;
-    variants: number;
-    brands: number;
-};
-export type ColourStatsGroup = {
-    key: string;
-    name: string;
-    productTypes: number;
-    variants: number;
-};
-/**
- * One cell of the brand x category x colour-family matrix — the shape that
- * answers questions no single dimension can, such as "how many whites does
- * Benjamin Moore offer in paint".
- */
-export type ColourStatsRow = {
-    /** Opaque brand id — the join key for brand reads. Never parse it. */
-    brandId: string;
-    brandSlug: string;
-    brandName: string;
-    /**
-     * Product-type key. NULL means these variants carry NO accepted primary
-     * product type — a real population, kept so the matrix sums to the corpus,
-     * not an error and not a residual bucket.
-     */
-    categoryKey: string | null;
-    family: string;
-    /**
-     * Distinct variants at this (brand, category, family) carrying an ACCEPTED
-     * `colour_family`. Not every variant of the brand.
-     */
-    variants: number;
-};
-/** How to narrow the matrix. Passing ANY of these asks for `rows`. */
-export type ColourStatsParams = {
-    /** `"brand,category"` — ask for the whole matrix, unscoped. */
-    groupBy?: string;
-    brandId?: string;
-    brandSlug?: string;
-    /**
-     * A product-type key, or the literal `"null"` for the unclassified
-     * population. Omitting it means every category — a different question.
-     */
-    categoryKey?: string;
-    family?: string;
-    limit?: number;
-};
-/** Where each section came from, how fresh it is, and what it does NOT answer. */
-export type ColourStatsBasis = {
-    corpus: string;
-    families: string;
-    groups: string;
-    groupsRefreshedAt: string | null;
-    groupsVariantCount: number;
-    /**
-     * Where `rows` came from, its freshness, and what it EXCLUDES — present only
-     * when `rows` is. Read it: the matrix deliberately omits Samplize, which is a
-     * sampling channel printing other manufacturers' colours rather than a maker.
-     */
-    rows?: string;
-    omissions: string[];
-};
-export type ColourStatsResponse = {
-    corpus: ColourStatsCorpus;
-    families: ColourStatsFamily[];
-    groups: ColourStatsGroup[];
-    /**
-     * The brand x category x colour-family matrix. Present ONLY when you asked
-     * for it; ABSENT means nobody asked, never that the matrix is empty.
-     *
-     * `families` above is NOT scoped by the same parameters and stays
-     * platform-wide under all of them. Scoped counts live here.
-     */
-    rows?: ColourStatsRow[];
-    /**
-     * Rows matching your query BEFORE the response cap — the honest total.
-     * A shortfall against `rows.length` means `rows` is a prefix.
-     */
-    rowsMatched?: number;
-    /** TRUE when the matrix exceeded the cap and `rows` is a prefix. */
-    rowsTruncated?: boolean;
-    basis: ColourStatsBasis;
-};

package/coordinate-client.d.ts

@@ -1,23 +0,0 @@
-/**
- * The COORDINATION lens: given several materials already chosen, what completes
- * them. A thin wrapper over the shared {@link HttpTransport};
- * `MaterialGraphClient.coordinate` delegates here.
- *
- * Extracted from `client.ts`, which sits above the repository's source-size
- * limit, in the same per-lens shape as `brands-client` / `codes-client` /
- * `colours-client`. Behaviour is unchanged.
- */
-import type { HttpTransport } from "./http-transport.js";
-import type { CoordinateInput, CoordinateResponse } from "./types.js";
-/**
- * THE QUESTION: "here is my whole scheme so far — what completes it?" The
- * multi-seed form of `pairings`: lift is SUMMED across seeds, so a companion
- * suiting one pick ranks below one suiting several. Returns demand-lift-ranked
- * companions with colour swatches and an annotate-only `colourFit` that never
- * reorders in v1.
- *
- * Instead use `pairings` for a single material, and `colours.palette()` when the
- * scheme is COLOURS rather than materials. Check `unresolved` before presenting:
- * a reference that resolved to nothing is named there, not dropped.
- */
-export declare const coordinate: (transport: HttpTransport, input: CoordinateInput, signal?: AbortSignal) => Promise<CoordinateResponse>;

package/coordinate-client.js

@@ -1,13 +0,0 @@
-import { resolveOperation } from "./operations.js";
-/**
- * THE QUESTION: "here is my whole scheme so far — what completes it?" The
- * multi-seed form of `pairings`: lift is SUMMED across seeds, so a companion
- * suiting one pick ranks below one suiting several. Returns demand-lift-ranked
- * companions with colour swatches and an annotate-only `colourFit` that never
- * reorders in v1.
- *
- * Instead use `pairings` for a single material, and `colours.palette()` when the
- * scheme is COLOURS rather than materials. Check `unresolved` before presenting:
- * a reference that resolved to nothing is named there, not dropped.
- */
-export const coordinate = async (transport, input, signal) => await transport.requestJson(resolveOperation("coordinate_materials"), { body: input, signal });

package/demand-batch-types.d.ts

@@ -1,118 +0,0 @@
-/**
- * Wire types for BATCH candidate demand enrichment — `POST /api/v1/demand/batch`.
- *
- * Split out of `types.ts` for the repository's source-file size budget, the same
- * reason `material-types.ts` and `catalog-discovery-types.ts` sit beside it;
- * re-exported from `types.ts`, so importers see no difference.
- *
- * THE LENS: this answers "how much is each of these already-chosen materials
- * actually specified?" — enrichment over a bounded id list you already hold. It
- * never resolves, ranks, reorders or discovers. Use
- * {@link MaterialGraphClient.demand} for one material named in free text,
- * {@link MaterialGraphClient.pairings} for what goes WITH a material, and
- * {@link MaterialGraphClient.search} to find candidates in the first place.
- */
-import type { VariantId } from "./identifiers.js";
-import type { DemandMomentum, DemandQuarter, DemandSignal, OpenEnum } from "./types.js";
-/**
- * Body for `POST /api/v1/demand/batch` — enrich 1–48 already-selected candidate
- * ids with their real specification demand, in input order and cardinality.
- */
-export type DemandBatchInput = {
-    /** 1–48 canonical variant ids. Order AND cardinality are preserved — duplicates are echoed, never collapsed. */
-    variantIds: VariantId[];
-    /** The behavioural signal to read demand from. Defaults to `sampled` (order co-occurrence) server-side. */
-    signal?: DemandSignal;
-    /** Optional declared context (e.g. `{ projectType: "hospitality" }`) — echoed for provenance, never used to rank or filter. */
-    context?: Record<string, string>;
-};
-/** Headline population behind the metric — this variant's own counts. */
-export type DemandBatchPopulation = {
-    specCount: number;
-    projectCount: number;
-    customerCount: number;
-};
-/** The consideration→specification funnel (project-grain; `exclusionRate` is annotate-only). */
-export type DemandBatchFunnel = {
-    consideredProjects: number;
-    specifiedProjects: number;
-    excludedCount: number;
-    exclusionRate: number;
-};
-/** Per-result guardrail status — present on `internal` (`mg:admin`) results only. */
-export type DemandBatchEvidence = {
-    belowPrivacyFloor: boolean;
-    belowQualityFloor: boolean;
-    suppressedForPublic: boolean;
-};
-/** A variant that carries a usable demand signal. */
-export type DemandBatchAvailableResult = {
-    variantId: VariantId;
-    state: "available";
-    population: DemandBatchPopulation;
-    /** Exact per-quarter counts (sparse — zero-spec quarters are absent). */
-    intervals: DemandQuarter[];
-    momentum: DemandMomentum;
-    /** The funnel; null when the signal is not `sampled` or no `considered` row/session exists. */
-    funnel: DemandBatchFunnel | null;
-    /** Exact guardrail evidence for `internal` callers; null for public. */
-    evidence: DemandBatchEvidence | null;
-};
-/**
- * A variant with a stats row that is below the public quality floor. We HAVE a
- * reading and are declining to publish it — not a claim that nobody specifies it.
- */
-export type DemandBatchInsufficientResult = {
-    variantId: VariantId;
-    state: "insufficient_data";
-};
-/**
- * A variant with no stats — indistinguishable from a privacy-suppressed one for
- * public callers, and therefore never reportable as "nobody specifies this".
- */
-export type DemandBatchNoSignalResult = {
-    variantId: VariantId;
-    state: "no_signal";
-};
-/** A requested id that resolves to no real variant. */
-export type DemandBatchUnknownResult = {
-    variantId: VariantId;
-    state: "unknown_variant";
-};
-/**
- * One discriminated result per input id, in input order and cardinality.
- *
- * ABSENT IS NOT ZERO: only `available` carries numbers. The other three states
- * each mean "no number to report", for three different reasons, and none of them
- * licenses "this material is not specified" — see each member.
- */
-export type DemandBatchResult = DemandBatchAvailableResult | DemandBatchInsufficientResult | DemandBatchNoSignalResult | DemandBatchUnknownResult;
-/** The `POST /api/v1/demand/batch` envelope. */
-export type DemandBatchResponse = {
-    /** The completed ingestion-session id these counts were mined in (the dataset generation). */
-    generationId: string;
-    metric: "specification_demand";
-    /** The metric universe — the window and signal the counts are scoped to. */
-    universe: {
-        window: "trailing_36mo";
-        signal: DemandSignal;
-        description: string;
-    };
-    /** The guardrail status under which `results` were projected. */
-    guardrail: {
-        audience: OpenEnum<"public" | "internal">;
-        minProjectCount: number;
-        minCustomerCount: number;
-    };
-    /** Outcome tallies over `results` — never a denominator for the metric. */
-    coverage: {
-        requested: number;
-        available: number;
-        insufficientData: number;
-        noSignal: number;
-        unknownVariant: number;
-    };
-    /** The echoed declared context, or null when none was supplied. */
-    context: Record<string, string> | null;
-    results: DemandBatchResult[];
-};

package/demand-types.d.ts

@@ -1,154 +0,0 @@
-/**
- * Wire types for the SINGLE-SEED demand reads — `GET /api/v1/demand` and
- * `POST /api/v1/pairings/coordinate`.
- *
- * Split out of `types.ts` for the repository's source-file size budget, the same
- * reason `material-types.ts` and `demand-batch-types.ts` sit beside it; both are
- * re-exported from `types.ts`, so importers see no difference.
- *
- * THE LENS: demand answers "how much is this specified, and what travels with
- * it?" from real order behaviour. It is not a search and not a recommendation
- * engine — every number is bounded by the `trailing_36mo` window and by the
- * {@link DemandSignal} it was read under, and a missing number means UNREAD, not
- * zero.
- */
-import type { ProductId, VariantId } from "./identifiers.js";
-import type { CompanionDemand, DemandMomentum, DemandQuarter, OpenEnum } from "./types.js";
-/** A resolved seed material (identity block shared by the demand reads). */
-export type DemandSeed = {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    brandSlug: string;
-    productId: ProductId;
-};
-/** Headline demand stats for a seed: counts, quarterly series, momentum. */
-export type MaterialDemandStats = {
-    specCount: number;
-    projectCount: number;
-    customerCount: number;
-    /** Sparse — a quarter with no activity is ABSENT, not a zero row. */
-    byQuarter: DemandQuarter[];
-    momentum: DemandMomentum;
-};
-/**
- * `getMaterialDemand` result, passed through verbatim by the `/demand` route.
- *
- * `demand: null` means NO READING — the seed did not resolve, or nothing cleared
- * the publication floor. It is never a reading of zero, and never licenses
- * "nobody specifies this".
- */
-export type MaterialDemandResult = {
-    found: boolean;
-    query: string;
-    seed: DemandSeed | null;
-    /** The only window v1 serves. Activity outside it is unread, not absent. */
-    window: "trailing_36mo";
-    demand: MaterialDemandStats | null;
-};
-/**
- * `getCoSpecifiedMaterials` result, passed through verbatim. The `companions`
- * list (materials specified alongside the seed) is included but left loosely
- * typed — there is no captured fixture to pin its full shape.
- *
- * `resolution` is the honest report on the free-text seed: `ambiguous` means the
- * phrase matched several materials and `seedAlternatives` holds them — pick one
- * and re-ask by `variantId` rather than treating the first as the answer.
- */
-export type CoSpecifiedResult = {
-    found: boolean;
-    resolution: OpenEnum<"resolved" | "ambiguous" | "not_found">;
-    query: string;
-    seed: DemandSeed | null;
-    seedCategory: string | null;
-    seedAlternatives: DemandSeed[];
-    companions?: unknown[];
-};
-/** The `/api/v1/demand` envelope — both domain reads side by side, verbatim. */
-export type DemandResponse = {
-    query: string;
-    demand: MaterialDemandResult;
-    cospec: CoSpecifiedResult;
-};
-/** Seed a demand read by EXACTLY ONE of `variantId` or `material`. */
-export type DemandParams = {
-    /** An exact variant id. Opaque — pass through verbatim. */
-    variantId?: VariantId;
-    /** Free text ("Brand Product Colour"), resolved server-side. May be ambiguous. */
-    material?: string;
-};
-export type CoordinateSeed = {
-    /** The input reference this seed resolved from. */
-    resolvedFrom: string;
-} & DemandSeed;
-export type CoordinateCompanion = {
-    /** Opaque — round-trip verbatim. */
-    variantId: VariantId;
-    brand: string;
-    product: string;
-    color: string | null;
-    variantName: string | null;
-    imageUrl: string | null;
-    brandSlug: string;
-    productId: ProductId;
-    /**
-     * How this companion relates to the SEED SET — the closest relation that
-     * applies to any seed.
-     *
-     * `companion` is foreign to every seed: a maker the caller did not pick.
-     * `brand_sibling` shares a brand with some seed. `colourway` is a seed's own
-     * product restyled, and completes nothing.
-     *
-     * READ IT BEFORE CLAIMING BREADTH. Measured across the live edges (MG-1007),
-     * 70.6% are same-brand and 24.3% are the seed's own product in another
-     * colourway; on a two-seed rail, 27 of 40 companions came from the seeds' own
-     * two brands. A surface headed "makers you haven't picked" that does not
-     * filter on this is making a claim the evidence does not support — the
-     * measured case showed two distinct makers under a heading promising seven.
-     *
-     * The server has always sent this field; it was absent from this interface
-     * until 2026-08-23, so consumers could not see it and hand-rolled the same
-     * comparison against `brandSlug` themselves.
-     */
-    relation: "companion" | "brand_sibling" | "colourway";
-    totalLift: number;
-    liftLabel: string;
-    seedMatchCount: number;
-    seedContributions: {
-        seedVariantId: VariantId;
-        lift: number;
-    }[];
-    demand: CompanionDemand | null;
-    swatches: {
-        hex: string;
-        proportion: number;
-    }[];
-    /** Annotate-only appearance similarity — never reorders companions in v1. */
-    colourFit: number | null;
-};
-/**
- * The `POST /api/v1/pairings/coordinate` envelope. `unresolved` lists the input
- * references that matched nothing — read it before presenting `companions` as
- * "what goes with your palette", because a companion set derived from two of
- * four seeds is a different claim.
- */
-export type CoordinateResponse = {
-    seeds: CoordinateSeed[];
-    /** Input references that resolved to no material. Never silently dropped. */
-    unresolved: string[];
-    window: "trailing_36mo";
-    companions: CoordinateCompanion[];
-};
-/** Body for `POST /api/v1/pairings/coordinate`. */
-export type CoordinateInput = {
-    /** Free-text material references, resolved server-side; misses land in `unresolved`. */
-    materials?: string[];
-    /** Exact variant ids. Opaque — pass through verbatim. */
-    variantIds?: VariantId[];
-    projectType?: string;
-    limit?: number;
-};

package/identify-types.d.ts

@@ -1,82 +0,0 @@
-/**
- * Public wire types for `POST /api/v1/identify` (MG-1672's `resolve_variant`
- * contract).
- *
- * These intentionally mirror the domain-owned Zod contract
- * (`@materialgraph/products/identify-contract`) rather than importing it: the
- * published SDK must carry no workspace package dependency.
- */
-/**
- * What `mg.identify()` accepts. Give `url` alone, or `code` with `brandId`
- * (from `mg.brands()`) when there is no page to read. `labels` are product
- * names visible on the page, sent only to tell several URL candidates apart -
- * they never widen a search or invent an identity on their own.
- */
-export type IdentifyVariantInput = {
-    url?: string;
-    code?: string;
-    brandId?: string;
-    labels?: string[];
-};
-/** One identified, placed or bounded-candidate subject. */
-export type IdentifySubject = {
-    kind: "variant" | "brand";
-    id: string;
-    name: string;
-    code?: string;
-    brand?: {
-        id: string;
-        name: string;
-    };
-};
-/** What stood behind an outcome. Exact and scoreless: never a similarity guess. */
-export type IdentifyEvidence = {
-    kind: "manufacturer-url" | "brand-homepage" | "manufacturer-code" | "visible-label";
-    url?: string;
-    detail: string;
-};
-/** The submitted URL, normalised, and the steps that normalisation took. Absent for a code-only call. */
-export type IdentifyReceipt = {
-    submittedUrl: string;
-    normalizedUrl: string;
-    normalizationSteps: string[];
-};
-type IdentifyResultBase = {
-    evidence: IdentifyEvidence[];
-    receipt?: IdentifyReceipt;
-};
-/**
- * Why nothing was identified. Absent and empty differ: this names what was
- * looked for and not found, never a similarity guess.
- */
-export type IdentifyUnresolvedReason = "no-stored-url" | "no-code-match";
-/** Exact identities only - no rung carries a similarity score. */
-export type IdentifyResult = (IdentifyResultBase & {
-    outcome: "identified";
-    subject: IdentifySubject & {
-        kind: "variant";
-    };
-}) | (IdentifyResultBase & {
-    outcome: "placed";
-    subject: IdentifySubject & {
-        kind: "brand";
-    };
-}) | (IdentifyResultBase & {
-    outcome: "ambiguous";
-    candidates: IdentifySubject[];
-    truncated: boolean;
-}) | (IdentifyResultBase & {
-    outcome: "unresolved";
-    reason: IdentifyUnresolvedReason;
-});
-/** The canonical callable-operation envelope returned by `identify()`. */
-export type IdentifyResponse = {
-    data: IdentifyResult;
-    meta: {
-        operationId: "retrieval.identify";
-        requestId: string;
-    };
-    links: Record<string, never>;
-    warnings: [];
-};
-export {};

package/material-composition-client.d.ts

@@ -1,21 +0,0 @@
-/**
- * The MATERIAL COMPOSITION lens: what a product is made of, and how far the
- * corpus that answers that question has got (MG-1969).
- *
- * Not `./composition-client.ts`, which wraps the slot pools a scheme composer
- * outside MaterialGraph reads.
- */
-import type { HttpTransport } from "./http-transport.js";
-import type { CompositionCorpusSummary } from "./material-composition-types.js";
-/**
- * THE QUESTION: "which product types can we answer that question for yet?"
- *
- * Coverage per product type, counted in Live SKUs as well as in tuples. Read
- * the SKU figure: one tuple can carry a hundred thousand SKUs or one, so a
- * corpus that resolved every rare tuple and none of the common ones reads as
- * good coverage counted by tuple.
- *
- * A type in `completeness.authoringQueue` has no bar set, which is never the
- * same as a bar it missed. Requires the `mg:read` scope.
- */
-export declare const compositionReport: (transport: HttpTransport, signal?: AbortSignal) => Promise<CompositionCorpusSummary>;

package/material-composition-client.js

@@ -1,13 +0,0 @@
-import { resolveOperation } from "./operations.js";
-/**
- * THE QUESTION: "which product types can we answer that question for yet?"
- *
- * Coverage per product type, counted in Live SKUs as well as in tuples. Read
- * the SKU figure: one tuple can carry a hundred thousand SKUs or one, so a
- * corpus that resolved every rare tuple and none of the common ones reads as
- * good coverage counted by tuple.
- *
- * A type in `completeness.authoringQueue` has no bar set, which is never the
- * same as a bar it missed. Requires the `mg:read` scope.
- */
-export const compositionReport = async (transport, signal) => await transport.requestJson(resolveOperation("get_composition_report"), { signal });