@instruments/materialgraph 0.6.0 → 0.6.1

package/codes-types.d.ts

@@ -13,18 +13,47 @@
  * ADVISORY ONLY: every verdict and the envelope carry the AHJ caveat — this is
  * model code as adopted, never a legal determination.
  */
+import type { VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /**
- * Badge a bounded set of materials against the code-requirement registry for one
- * (jurisdiction, occupancy, space, sprinklered) context. `results` preserve
- * input order and cardinality (duplicate ids are echoed).
+ * A code context: the space the registry is queried for.
+ *
+ * CONDITIONAL REQUIREMENT — two axes must END UP resolved, and each may be
+ * stated OR correlated. Every field below is optional in the type because the
+ * validator resolves them per axis independently; the rule it enforces at
+ * runtime is:
+ *
+ * > occupancyGroup, resolved = `input.occupancyGroup` ?? correlate(roomType)
+ * > spaceType,      resolved = `input.spaceType`      ?? correlate(roomType)
+ *
+ * and either resolving to nothing is a 400, verbatim:
+ *
+ * - `"An occupancy group is required — state occupancyGroup, or a roomType that
+ *   correlates to one."`
+ * - `"A space type is required — state spaceType, or a roomType that correlates
+ *   to one."`
+ * - `"Room type \"{roomType}\" does not correlate to an IBC occupancy group —
+ *   state occupancyGroup explicitly."`
+ * - `"Room type \"{roomType}\" does not correlate to a Table 803.13 finish
+ *   location — state spaceType explicitly."`
+ *
+ * So: give `occupancyGroup` + `spaceType`, or give `roomType` and let both
+ * correlate, or mix them — an explicit axis always wins over a correlated one,
+ * and a room is only consulted for an axis you did not state. Correlation never
+ * guesses: a room that maps to neither is an error naming the axis, and the
+ * response's `resolvedContext` is where you audit what was inferred for you.
+ *
+ * Discover every accepted value — jurisdictions, occupancy groups, finish
+ * locations, and the room correlations themselves — from
+ * {@link CodesClient.context}. Nothing here should be hardcoded.
  */
 export interface CodeContextRequest {
-    /** A seeded jurisdiction id (e.g. `"us-tx"`); an unknown id is a 400. */
+    /** A seeded jurisdiction id (e.g. `"us-tx"`); an unknown id is a 400 listing the seeded set. */
     jurisdictionId: string;
     /**
      * The IBC occupancy group for the space (e.g. `"I-2"` hospital, `"A-2"`
-     * restaurant). Required unless `roomType` correlates to one.
+     * restaurant). Required unless `roomType` correlates to one. An uncovered
+     * group is a 400 listing the covered ones.
      */
     occupancyGroup?: string;
     /**
@@ -42,8 +71,12 @@ export interface CodeContextRequest {
     sprinklered: boolean;
 }
 export interface CodeAdvisoryInput extends CodeContextRequest {
-    /** 1–100 opaque variant ids to badge, echoed back in `results` in this exact order. */
-    variantIds: string[];
+    /**
+     * 1–100 opaque variant ids to badge, echoed back in `results` in this exact
+     * order and cardinality (duplicates are echoed, never collapsed). Preserve
+     * them verbatim — never parse or construct one.
+     */
+    variantIds: VariantId[];
 }
 /** The resolved jurisdiction the verdicts were evaluated against. */
 export interface CodeAdvisoryJurisdiction {
@@ -101,7 +134,15 @@ export interface CodeRequirementThreshold {
         unit: string;
     } | null;
 }
-/** The accepted fact a verdict was decided from (null when the material carried none). */
+/**
+ * The accepted fact a verdict was decided from — null when the material carried
+ * none, which is exactly the case that produces `verdict: "unknown"`.
+ *
+ * `confidence` and `sourceBasis` are the strength of the fact, not of the code
+ * reading. Quote them whenever you quote the badge: a `meets` resting on a
+ * `derived` value at low confidence is a materially different statement from one
+ * resting on a `tested` figure.
+ */
 export interface CodeRequirementEvidence {
     attributeId: OpenEnum<"fire_classifications" | "slip_resistance_dcof">;
     value: string;
@@ -114,7 +155,14 @@ export interface CodeRequirementVerdict {
     dimension: OpenEnum<"fire" | "floor" | "slip" | "decorative">;
     section: string;
     requirement: CodeRequirementThreshold;
-    /** `meets` / `shortfall` / `unknown` — `unknown` when no defensible fact maps onto `scale`. */
+    /**
+     * What may be said about this material against this requirement:
+     *  - `meets` — a defensible fact clears the threshold. Advisory, still not a
+     *    determination.
+     *  - `shortfall` — a defensible fact FAILS to clear it. A real negative.
+     *  - `unknown` — no defensible fact maps onto `scale`. NOT a failure and NOT a
+     *    pass: "no comparable rating on file". Never present it as either.
+     */
     verdict: OpenEnum<"meets" | "shortfall" | "unknown">;
     evidence: CodeRequirementEvidence | null;
     /** The AHJ advisory caveat — model code as adopted, never a legal determination. */
@@ -126,6 +174,16 @@ export interface CodeRequirementVerdict {
  * `not_applicable` (nothing applied) is deliberately distinct from `meets`.
  */
 export interface CodeAdvisorySummary {
+    /**
+     * The rolled-up card, and what each token licenses:
+     *  - `meets` — every applicable requirement was `meets`. Advisory pass.
+     *  - `shortfall` — at least one requirement failed on real evidence. Blocking.
+     *  - `unverified` — nothing failed, but something is `unknown`. COMMON, and
+     *    never a pass: it means "no comparable rating is on file". Show it as an
+     *    open question, not a green tick.
+     *  - `not_applicable` — the space imposes nothing this material answers for.
+     *    Deliberately distinct from `meets`: it is silence, not approval.
+     */
     status: OpenEnum<"meets" | "shortfall" | "unverified" | "not_applicable">;
     /** One deterministic sentence naming what failed, e.g. `"Falls short on fire for A-2 corridors."`. */
     headline: string;
@@ -134,7 +192,8 @@ export interface CodeAdvisorySummary {
 }
 /** Per-variant advisory outcome, in input order. */
 export interface CodeAdvisoryVariantResult {
-    variantId: string;
+    /** Opaque — echoed verbatim from `variantIds`, in that position. */
+    variantId: VariantId;
     /** `evaluated` when the id resolved; `unknown_variant` (with `requirements: []`) when it did not. */
     state: OpenEnum<"evaluated" | "unknown_variant">;
     /** What this material is and what it was scored against. Null only for `state: "unknown_variant"`. */
@@ -168,7 +227,14 @@ export interface ResolvedCodeContext {
     /** The `ms_room` term the axes were correlated from, or null. */
     roomType: string | null;
 }
-/** How far a jurisdiction's rows have been reviewed against that AHJ's own tables. */
+/**
+ * How far a jurisdiction's rows have been reviewed against that AHJ's own tables.
+ *
+ *  - `thorough` — reviewed against this jurisdiction's own adopted tables.
+ *  - `model_baseline` — UNAMENDED model IBC stood in, because that AHJ's own
+ *    amendments have not been reviewed. Local amendments may be stricter, so
+ *    say "per model IBC" rather than naming the jurisdiction as the authority.
+ */
 export type CodeCoverageTier = OpenEnum<"thorough" | "model_baseline">;
 export interface CodeJurisdictionSummary {
     id: string;

package/colours-client.d.ts

@@ -17,6 +17,20 @@
  * materialized view refreshed on a schedule, not on write, so a caller can and
  * should check how much of the corpus the answer actually covers before
  * treating it as complete. The two SEARCH responses are live and uncached.
+ *
+ * ROUTING OUT OF THIS NAMESPACE. Colour is a lens, and these are not the only
+ * doors into it:
+ * - ONE colour → `mg.byColour({ hex })`. This namespace's `palette` is for N
+ *   colours at stated proportions, which is a different ranking, not a
+ *   convenience wrapper.
+ * - A colour NAME rather than a hex → `mg.resolveColour(name)` first.
+ * - Colour WORDS (families, moods, undertones) → `mg.colourFacets()`.
+ * - Walking the corpus by lightness/vividness → `mg.browse({ sort })`.
+ * - Colour as one signal among words, a seed and a mood → `mg.search(...)`.
+ *
+ * And the honesty rule the whole lens rests on: every colour here is DERIVED
+ * FROM PRODUCT IMAGERY, not declared by the manufacturer. Report visual
+ * likeness, never a stated colour specification.
  */
 import type { CategoryColourProfilesResponse, ColourProfilesParams, ColourStatsResponse } from "./colour-aggregate-types.js";
 import type { QueryParams } from "./http-transport.js";
@@ -31,8 +45,14 @@ export declare class ColoursClient {
     #private;
     constructor(transport: ColoursTransport);
     /**
-     * The representative colour palette of 1–8 categories in ONE call
-     * (GET `/api/v1/colours/profiles`).
+     * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
+     * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).
+     *
+     * An aggregate over a category, not a list of materials: use `mg.byColour()` or
+     * `mg.search()` when you want the materials themselves, and
+     * {@link ColoursClient.stats} for coverage across the whole corpus rather than
+     * one category's palette. Check `basis` — this reads a scheduled materialized
+     * view, so it can lag the catalog.
      *
      * `groupBy: "group"` takes product-type GROUP keys and merges every leaf type
      * under a group into one histogram BEFORE ranking — a group's palette, not the
@@ -54,6 +74,14 @@ export declare class ColoursClient {
      */
     profiles(params: ColourProfilesParams, signal?: AbortSignal): Promise<CategoryColourProfilesResponse>;
     /**
+     * THE QUESTION: "how much colour does the graph hold AT ALL?" — corpus-level
+     * coverage, before you trust any colour answer.
+     *
+     * The sanity check under every other colour call. Use
+     * {@link ColoursClient.profiles} for one category's palette and
+     * `mg.colourFacets()` for the vocabulary. `basis.omissions` lists what this
+     * call deliberately does not answer — read it rather than assuming silence.
+     *
      * Corpus colour coverage (GET `/api/v1/colours/stats`): how much of the graph
      * carries colour at all, the split across the canonical colour families, and
      * coverage per product-type group. `basis` states the source and freshness of
@@ -62,8 +90,12 @@ export declare class ColoursClient {
      */
     stats(signal?: AbortSignal): Promise<ColourStatsResponse>;
     /**
-     * Find materials that go with a WHOLE PALETTE — N colours at once, not one
-     * colour repeated (POST `/api/v1/search/palettes`).
+     * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at
+     * stated proportions, not one colour repeated (POST `/api/v1/search/palettes`).
+     *
+     * Use `mg.byColour()` for a single colour, {@link ColoursClient.gradient} when
+     * the colours form an ordered TRANSITION rather than a set, and
+     * `mg.coordinate()` when the scheme is made of materials rather than colours.
      *
      * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
      * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
@@ -90,8 +122,11 @@ export declare class ColoursClient {
      */
     palette(input: SearchPaletteInput, signal?: AbortSignal): Promise<SearchPaletteResponse>;
     /**
-     * Find materials that move ALONG a colour transition — "cream to rust", in
-     * order (POST `/api/v1/search/gradients`).
+     * THE QUESTION: "what moves from this colour to that one?" — materials that
+     * travel ALONG a transition, in order (POST `/api/v1/search/gradients`).
+     *
+     * Order is the whole point: use {@link ColoursClient.palette} when the colours
+     * are a set rather than a path, and `mg.byColour()` for a single colour.
      *
      * Not a palette: the score is multiplied by `coverage`, the share of the path
      * the candidate actually spans, so a material owning only one end ranks below

package/colours-client.js

@@ -4,8 +4,14 @@ export class ColoursClient {
         this.#transport = transport;
     }
     /**
-     * The representative colour palette of 1–8 categories in ONE call
-     * (GET `/api/v1/colours/profiles`).
+     * THE QUESTION: "what colours does this CATEGORY come in?" — the representative
+     * palette of 1–8 categories in ONE call (GET `/api/v1/colours/profiles`).
+     *
+     * An aggregate over a category, not a list of materials: use `mg.byColour()` or
+     * `mg.search()` when you want the materials themselves, and
+     * {@link ColoursClient.stats} for coverage across the whole corpus rather than
+     * one category's palette. Check `basis` — this reads a scheduled materialized
+     * view, so it can lag the catalog.
      *
      * `groupBy: "group"` takes product-type GROUP keys and merges every leaf type
      * under a group into one histogram BEFORE ranking — a group's palette, not the
@@ -34,6 +40,14 @@ export class ColoursClient {
         }, signal);
     }
     /**
+     * THE QUESTION: "how much colour does the graph hold AT ALL?" — corpus-level
+     * coverage, before you trust any colour answer.
+     *
+     * The sanity check under every other colour call. Use
+     * {@link ColoursClient.profiles} for one category's palette and
+     * `mg.colourFacets()` for the vocabulary. `basis.omissions` lists what this
+     * call deliberately does not answer — read it rather than assuming silence.
+     *
      * Corpus colour coverage (GET `/api/v1/colours/stats`): how much of the graph
      * carries colour at all, the split across the canonical colour families, and
      * coverage per product-type group. `basis` states the source and freshness of
@@ -44,8 +58,12 @@ export class ColoursClient {
         return this.#transport.get("get_colour_stats", undefined, signal);
     }
     /**
-     * Find materials that go with a WHOLE PALETTE — N colours at once, not one
-     * colour repeated (POST `/api/v1/search/palettes`).
+     * THE QUESTION: "what goes with this WHOLE PALETTE?" — N colours at once, at
+     * stated proportions, not one colour repeated (POST `/api/v1/search/palettes`).
+     *
+     * Use `mg.byColour()` for a single colour, {@link ColoursClient.gradient} when
+     * the colours form an ordered TRANSITION rather than a set, and
+     * `mg.coordinate()` when the scheme is made of materials rather than colours.
      *
      * Each colour scores `sim × prop`: `sim` is OKLab closeness on the same
      * mapping `byColour` ranks with, and `prop` rewards a candidate whose own
@@ -74,8 +92,11 @@ export class ColoursClient {
         return this.#transport.post("search_by_palette", input, signal);
     }
     /**
-     * Find materials that move ALONG a colour transition — "cream to rust", in
-     * order (POST `/api/v1/search/gradients`).
+     * THE QUESTION: "what moves from this colour to that one?" — materials that
+     * travel ALONG a transition, in order (POST `/api/v1/search/gradients`).
+     *
+     * Order is the whole point: use {@link ColoursClient.palette} when the colours
+     * are a set rather than a path, and `mg.byColour()` for a single colour.
      *
      * Not a palette: the score is multiplied by `coverage`, the share of the path
      * the candidate actually spans, so a material owning only one end ranks below

package/composition-types.d.ts

@@ -12,6 +12,7 @@
  * TOLERANT-PARSING CONTRACT: response enums are widened with {@link OpenEnum}
  * so a new server value still type-checks; objects are read structurally.
  */
+import type { RunId, SchemeId, SlotId, VariantId } from "./identifiers.js";
 import type { OpenEnum } from "./types.js";
 /**
  * The four v1 variation axes. Request-side, so this is a STRICT union (the
@@ -25,21 +26,22 @@ export type VaryAxis = "palette" | "sustainability" | "brandDiversity" | "priceT
 export declare const VARY_AXES: readonly VaryAxis[];
 /** Pin one slot to a specific variant so vary re-derives only the rest. */
 export interface SchemeLock {
-    slotId: string;
-    /** Must equal that slot's CURRENT pick in the source scheme. */
-    variantId: string;
+    slotId: SlotId;
+    /** Must equal that slot's CURRENT pick in the source scheme. Opaque. */
+    variantId: VariantId;
 }
 /** Candidate exclusions applied on top of the automatic source-pick exclusion. */
 export interface SchemeExclusions {
-    variantIds?: string[];
+    /** Opaque variant ids to keep out of every slot. */
+    variantIds?: VariantId[];
     brandSlugs?: string[];
 }
 /** Body for `POST /api/v1/schemes/vary` ({@link MaterialGraphClient.varyScheme}). */
 export interface VarySchemesRequest {
-    /** The succeeded `compose-material-schemes` Run to vary from. */
-    runId: string;
+    /** The succeeded `compose-material-schemes` Run to vary from. Opaque. */
+    runId: RunId;
     /** Which scheme in the Run is option A. Defaults to the Run's FIRST scheme. */
-    schemeId?: string;
+    schemeId?: SchemeId;
     axis: VaryAxis;
     /** Slots kept pinned to their source pick; only unlocked slots re-derive. */
     locks?: SchemeLock[];
@@ -59,8 +61,8 @@ export interface ComposeAnchorInput {
     element: SlotElement;
     /** Optional named space to scope the anchor to (matched by name/slug). */
     spaceName?: string;
-    /** An exact catalog variant id. Mutually exclusive with `query`. */
-    variantId?: string;
+    /** An exact catalog variant id. Opaque. Mutually exclusive with `query`. */
+    variantId?: VariantId;
     /** Free-text "Brand Product Colour". Mutually exclusive with `variantId`. */
     query?: string;
     /** Display name for slot naming and warnings. */
@@ -92,6 +94,7 @@ export interface CompliancePreset {
  * every candidate but never exclude one.
  */
 export interface ComposeMaterialSchemesInput {
+    /** The uploaded source-material batch to compose from. Opaque. */
     batchId: string;
     count?: number;
     seed?: number;
@@ -137,12 +140,13 @@ export interface CompositionMatch {
 }
 /** One slot's chosen material plus the reason it was picked. */
 export interface CompositionPick {
-    slotId: string;
+    slotId: SlotId;
     slotName: string;
     spaceId?: string | null;
     element?: string | null;
     material: {
-        variantId: string;
+        /** Opaque — round-trip verbatim into the material lenses. */
+        variantId: VariantId;
         brand: string;
         product: string;
         variant: string;
@@ -171,12 +175,16 @@ export interface CompositionObjective {
 }
 /** A hydrated scheme: one pick per slot, plus its objective breakdown. */
 export interface CompositionScheme {
-    schemeId: string;
+    schemeId: SchemeId;
     title: string;
     picks: CompositionPick[];
     objective: CompositionObjective;
 }
-/** How far short of the request the derivation fell, with honest reasons. */
+/**
+ * How far short of the request the derivation fell, with honest reasons.
+ * `produced < requested` is a real answer, not an error — `reasons` says why,
+ * and a null shortfall means nothing fell short.
+ */
 export interface CompositionShortfall {
     requested: number;
     produced: number;
@@ -185,9 +193,9 @@ export interface CompositionShortfall {
 /** The axis + source provenance stamped onto every varied scheme. */
 export interface VaryProvenance {
     axis: VaryAxis;
-    sourceRunId: string;
-    sourceSchemeId: string;
-    lockedSlotIds: string[];
+    sourceRunId: RunId;
+    sourceSchemeId: SchemeId;
+    lockedSlotIds: SlotId[];
     /**
      * Human-readable notes recording exactly what the axis did — counts, not
      * adjectives (e.g. "brandDiversity: hard-excluded 2 brand(s) appearing ≥2×").
@@ -330,11 +338,12 @@ export interface CompositionAnsweredPayload {
  * slot: how many were considered and the top picks (≤5) hydrated for identity.
  */
 export interface SlotPoolEventPayload {
-    slotId: string;
+    slotId: SlotId;
     slotName: string;
+    /** How many candidates were WEIGHED, not how many qualified. */
     considered: number;
     top: Array<{
-        variantId: string;
+        variantId: VariantId;
         brand: string;
         product: string;
         imageUrl: string | null;

package/demand-batch-types.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 interface 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 interface DemandBatchPopulation {
+    specCount: number;
+    projectCount: number;
+    customerCount: number;
+}
+/** The consideration→specification funnel (project-grain; `exclusionRate` is annotate-only). */
+export interface DemandBatchFunnel {
+    consideredProjects: number;
+    specifiedProjects: number;
+    excludedCount: number;
+    exclusionRate: number;
+}
+/** Per-result guardrail status — present on `internal` (`mg:admin`) results only. */
+export interface DemandBatchEvidence {
+    belowPrivacyFloor: boolean;
+    belowQualityFloor: boolean;
+    suppressedForPublic: boolean;
+}
+/** A variant that carries a usable demand signal. */
+export interface 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 interface 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 interface DemandBatchNoSignalResult {
+    variantId: VariantId;
+    state: "no_signal";
+}
+/** A requested id that resolves to no real variant. */
+export interface 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 interface 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-batch-types.js

@@ -0,0 +1 @@
+export {};

package/demand-types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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 interface 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 interface 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 interface 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 interface 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 interface DemandResponse {
+    query: string;
+    demand: MaterialDemandResult;
+    cospec: CoSpecifiedResult;
+}
+/** Seed a demand read by EXACTLY ONE of `variantId` or `material`. */
+export interface 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 interface CoordinateSeed extends DemandSeed {
+    /** The input reference this seed resolved from. */
+    resolvedFrom: string;
+}
+export interface CoordinateCompanion {
+    /** Opaque — round-trip verbatim. */
+    variantId: VariantId;
+    brand: string;
+    product: string;
+    color: string | null;
+    variantName: string | null;
+    imageUrl: string | null;
+    brandSlug: string;
+    productId: ProductId;
+    totalLift: number;
+    liftLabel: string;
+    seedMatchCount: number;
+    seedContributions: Array<{
+        seedVariantId: VariantId;
+        lift: number;
+    }>;
+    demand: CompanionDemand | null;
+    swatches: Array<{
+        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 interface 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 interface 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/demand-types.js

@@ -0,0 +1 @@
+export {};