@instruments/materialgraph 0.9.1 → 0.11.0

package/source-material-validation.js

@@ -11,12 +11,16 @@
  * nothing at run time. This is the run-time half, and it must ACCEPT and REJECT
  * exactly what the schema does — pinned by `source-material-parity.test.ts`.
  *
- * TWO CONTRACT PROPERTIES IT ENFORCES, both easy to lose in a refactor:
+ * THREE CONTRACT PROPERTIES IT ENFORCES, each easy to lose in a refactor:
  *   1. `analyses` is REQUIRED and an array on every file. `[]` means "nothing
  *      computed yet"; an absent field is a broken response, not an empty one.
  *      Preprocessing is manual today and automatic later — only the trigger
  *      changes, never this contract.
- *   2. `result` is a JSON record all the way down (`z.json()`), not `unknown`.
+ *   2. `comments` is REQUIRED and an array on every file, and every root comment
+ *      carries a REQUIRED `replies` array. Same distinction: "nobody said
+ *      anything about this file" is a state the client draws, and an absent
+ *      field is a malformed response.
+ *   3. `result` is a JSON record all the way down (`z.json()`), not `unknown`.
  *      See `requireJsonValue` for why the schema is that strict and why this
  *      mirror cannot actually fire over the wire.
  *
@@ -30,7 +34,7 @@
  * permanent contract, and promoting it later is additive.
  */
 import { MaterialGraphError } from "./errors.js";
-import { requireArray, requireEnum, requireSafeInteger, requireJsonRecord, requireNonEmptyString, requireRecord, requireString, } from "./validation.js";
+import { requireArray, requireBoolean, requireEnum, requireSafeInteger, requireJsonRecord, requireNonEmptyString, requireNullableTrimmedBoundedString, requireRecord, requireString, requireTrimmedBoundedString, } from "./validation.js";
 /** `sourceImageAnalysisKindSchema` members, verbatim. */
 const ANALYSIS_KINDS = ["scene_match"];
 /** `sourceImageAnalysisStatusSchema` members, verbatim. */
@@ -61,12 +65,67 @@ function checkAnalysis(value, what, fail) {
         analysedAt: requireNonEmptyString(record.analysedAt, `${what}.analysedAt`, fail),
     };
 }
+/** `sourceMaterialCommentAuthorSchema`'s `attribution` members, verbatim. */
+const COMMENT_ATTRIBUTIONS = ["reported"];
+/** The canonical cap on both author fields: `.trim().min(1).max(160)`. */
+const AUTHOR_FIELD_MAX = 160;
+/**
+ * A reply, and the shared half of a root comment.
+ *
+ * `body`, `commentId` and `createdAt` are `.min(1)` canonically — fields this
+ * endpoint introduces, where an empty value carries nothing a client could
+ * render. `author.organisation` is nullable, NOT optional: `null` is the answer
+ * for a note with no organisation, and an absent key is a malformed body.
+ *
+ * The author fields are `.trim().min(1).max(160)` canonically and are mirrored
+ * as exactly that. A plain non-empty check — which is what this used to do —
+ * disagreed with the schema in both directions: it accepted `"   "`, which the
+ * schema rejects once trimmed, and accepted a name of any length, which the
+ * schema caps. A validator that is looser than the contract is a validator that
+ * lets the two drift without anything failing.
+ */
+function checkCommentBase(record, what, fail) {
+    const author = requireRecord(record.author, `${what}.author`, fail);
+    const recordedBy = requireRecord(record.recordedBy, `${what}.recordedBy`, fail);
+    return {
+        commentId: requireNonEmptyString(record.commentId, `${what}.commentId`, fail),
+        author: {
+            name: requireTrimmedBoundedString(author.name, `${what}.author.name`, AUTHOR_FIELD_MAX, fail),
+            organisation: requireNullableTrimmedBoundedString(author.organisation, `${what}.author.organisation`, AUTHOR_FIELD_MAX, fail),
+            // Closed here, matching the canonical `z.literal("reported")`, while the
+            // published type is `OpenEnum` so a newer server value keeps
+            // type-checking — the same split the analysis enums make.
+            attribution: requireEnum(author.attribution, COMMENT_ATTRIBUTIONS, `${what}.author.attribution`, fail),
+        },
+        recordedBy: {
+            principalId: requireNonEmptyString(recordedBy.principalId, `${what}.recordedBy.principalId`, fail),
+        },
+        body: requireNonEmptyString(record.body, `${what}.body`, fail),
+        createdAt: requireNonEmptyString(record.createdAt, `${what}.createdAt`, fail),
+    };
+}
+function checkComment(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    // Same reasoning as `analyses`: no `.default([])` canonically, so an absent
+    // `replies` is malformed rather than empty.
+    const replies = requireArray(record.replies, `${what}.replies`, fail);
+    return {
+        ...checkCommentBase(record, what, fail),
+        replies: replies.map((reply, index) => checkCommentBase(requireRecord(reply, `${what}.replies[${index}]`, fail), `${what}.replies[${index}]`, fail)),
+    };
+}
 function checkFile(value, what, fail) {
     const record = requireRecord(value, what, fail);
     // NOT `requireDefaultedArray`: the schema has no `.default([])`, so an absent
     // `analyses` is a malformed body rather than an empty one. Keeping that
-    // distinction is the whole point of the always-an-array contract.
+    // distinction is the whole point of the always-an-array contract. `comments`
+    // is required for the same reason: "nobody has said anything" and "the server
+    // forgot to tell you" are different answers.
     const analyses = requireArray(record.analyses, `${what}.analyses`, fail);
+    const comments = requireArray(record.comments, `${what}.comments`, fail);
+    // Required, not defaulted: "you are seeing the whole thread" is a claim the
+    // server makes or does not, never one a client should infer from a length.
+    const commentsTruncated = requireBoolean(record.commentsTruncated, `${what}.commentsTruncated`, fail);
     // `requireString`, NOT `requireNonEmptyString`, for the fields this endpoint
     // INHERITS from the shared source-material contract (`sourceId`, `sha256`,
     // `url` — plus `batchId`/`createdAt` below). Those are plain `z.string()`
@@ -91,9 +150,13 @@ function checkFile(value, what, fail) {
         // fields is a canonical change to a schema shared with the upload path, and
         // belongs in its own ticket with this mirror following after.
         bytes: requireSafeInteger(record.bytes, `${what}.bytes`, fail),
-        pages: record.pages === null ? null : requireSafeInteger(record.pages, `${what}.pages`, fail),
+        pages: record.pages === null
+            ? null
+            : requireSafeInteger(record.pages, `${what}.pages`, fail),
         url: requireString(record.url, `${what}.url`, fail),
         analyses: analyses.map((analysis, index) => checkAnalysis(analysis, `${what}.analyses[${index}]`, fail)),
+        comments: comments.map((comment, index) => checkComment(comment, `${what}.comments[${index}]`, fail)),
+        commentsTruncated,
     };
 }
 /** Validate a batch-detail body, returning it typed, or throw explaining why. */
@@ -107,3 +170,49 @@ export function checkSourceMaterialBatchDetail(value, batchId) {
         sources: sources.map((file, index) => checkFile(file, `body.sources[${index}]`, fail)),
     };
 }
+function commentsFailure(verb, sourceId) {
+    return (reason) => MaterialGraphError.unexpected(`${verb} .../sources/${sourceId}/comments returned a malformed body: ${reason}`);
+}
+/** Validate a comment-thread body, returning it typed, or throw explaining why. */
+export function checkSourceMaterialCommentThread(value, sourceId) {
+    const fail = commentsFailure("GET", sourceId);
+    const record = requireRecord(value, "body", fail);
+    const comments = requireArray(record.comments, "body.comments", fail);
+    return {
+        sourceId: requireString(record.sourceId, "body.sourceId", fail),
+        comments: comments.map((comment, index) => checkComment(comment, `body.comments[${index}]`, fail)),
+        truncated: requireBoolean(record.truncated, "body.truncated", fail),
+    };
+}
+/** `storedSourceMaterialCommentSchema`'s discriminator members, verbatim. */
+const STORED_COMMENT_KINDS = ["root", "reply"];
+/**
+ * Validate a stored comment, following its `kind` discriminator.
+ *
+ * The two branches are checked as the two DIFFERENT shapes they are: a root must
+ * carry `replies`, a reply must carry `parentCommentId` and must not be assumed
+ * to carry `replies` at all. Validating both as the root shape is exactly the
+ * defect this discriminated union was added to fix, and a mirror that did it
+ * would put the lie back on the client side.
+ */
+function checkStoredComment(value, what, fail) {
+    const record = requireRecord(value, what, fail);
+    const kind = requireEnum(record.kind, STORED_COMMENT_KINDS, `${what}.kind`, fail);
+    if (kind === "reply") {
+        return {
+            kind: "reply",
+            ...checkCommentBase(record, what, fail),
+            parentCommentId: requireNonEmptyString(record.parentCommentId, `${what}.parentCommentId`, fail),
+        };
+    }
+    return { kind: "root", ...checkComment(record, what, fail) };
+}
+/** Validate a posted-comment body, returning it typed, or throw explaining why. */
+export function checkPostSourceMaterialCommentResult(value, sourceId) {
+    const fail = commentsFailure("POST", sourceId);
+    const record = requireRecord(value, "body", fail);
+    return {
+        sourceId: requireString(record.sourceId, "body.sourceId", fail),
+        comment: checkStoredComment(record.comment, "body.comment", fail),
+    };
+}

package/spec-facet-types.d.ts

@@ -0,0 +1,53 @@
+export interface SpecFacetValue {
+    value: string;
+    variants: number;
+    brands: number;
+    label?: string;
+}
+/**
+ * A NUMERIC facet's observed span and the coverage behind it.
+ *
+ * A range, not buckets — no bucketing scheme has been decided, and one invented
+ * on the wire would be treated as canonical by everyone who read it. Both bounds
+ * are INCLUSIVE, matching `specRange`.
+ *
+ * READ `variants` BEFORE TRUSTING A FILTER. It is how many variants carry a
+ * value that parses as a number, i.e. how much of the corpus a range can reach;
+ * a facet that exists says the attribute is queryable, not that it is populated.
+ * `unparseableVariants` is the honesty companion: values recorded here that are
+ * not numbers, which a range EXCLUDES rather than reading as zero.
+ */
+export interface SpecFacetRange {
+    min: number;
+    max: number;
+    variants: number;
+    unparseableVariants: number;
+}
+export interface SpecFacet {
+    attributeId: string;
+    name: string;
+    isArray: boolean;
+    /**
+     * How this facet is queried. `token` — pick a value from `values` and send it
+     * as `attribute:value`. `numeric` — `values` is EMPTY and `range` carries the
+     * span; send inclusive bounds via `specRangeCriterion` instead.
+     */
+    kind: "token" | "numeric" | (string & {});
+    brands: number;
+    /** EMPTY for a `numeric` facet, which has no token vocabulary. */
+    values: SpecFacetValue[];
+    /** Present ONLY on a `numeric` facet. */
+    range?: SpecFacetRange;
+    description?: string;
+}
+export interface SpecFacetsListResponse {
+    mode: "facets";
+    count: number;
+    facets: SpecFacet[];
+}
+export interface SpecFacetsDistributionResponse {
+    mode: "distribution";
+    attributeId: string;
+    count: number;
+    values: SpecFacetValue[];
+}

package/spec-facet-types.js

@@ -0,0 +1,7 @@
+// ── Specification facets + attribute values ─────────────────────────────────
+//
+// Hand-maintained mirror of the `SpecificationFacet` 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.
+export {};

package/specifications.d.ts

@@ -57,6 +57,32 @@ export declare function certificationProgramme(programme: string): Certification
  * client.bySpec([specCriterion("primary_material", "textile"), specCriterion("fire_classifications", "astm_e84_class_a")]);
  */
 export declare function specCriterion(attributeId: string, value: string): string;
+/**
+ * An `attribute:min..max` RANGE criterion string for `bySpec`, for a
+ * NUMBER-valued spec (`light_reflectance_value`, `nrc_rating`,
+ * `slip_resistance_dcof`, …). Pass the result in `bySpec`'s `ranges` option.
+ *
+ * BOTH BOUNDS ARE INCLUSIVE — `{ min: 60 }` matches a value of exactly 60 —
+ * because spec language is written that way ("LRV of 60 or more", "DCOF ≥ 0.42")
+ * and because inclusive-both-ends means adjacent ranges overlap at the join
+ * rather than leaving a gap that hides products.
+ *
+ * At least one bound is REQUIRED: a range with neither is a presence check, and
+ * this throws rather than sending a criterion the server would have to refuse.
+ * Discover which attributes take a range — and the span they actually occupy —
+ * from `specificationFacets()`: those are the facets with `kind: "numeric"`.
+ *
+ * @example
+ * // light paints, every brand at once
+ * client.bySpec([], { ranges: [specRangeCriterion("light_reflectance_value", { min: 60 })] });
+ * @example
+ * // a mid-tone band
+ * specRangeCriterion("light_reflectance_value", { min: 30, max: 45 }); // "light_reflectance_value:30..45"
+ */
+export declare function specRangeCriterion(attributeId: string, bounds: {
+    min?: number;
+    max?: number;
+}): string;
 /**
  * An `attribute:value` criterion string for `bySpec` that filters by
  * certification PROGRAMME across all four certification buckets.

package/specifications.js

@@ -65,6 +65,38 @@ export function certificationProgramme(programme) {
 export function specCriterion(attributeId, value) {
     return `${attributeId}:${value}`;
 }
+/**
+ * An `attribute:min..max` RANGE criterion string for `bySpec`, for a
+ * NUMBER-valued spec (`light_reflectance_value`, `nrc_rating`,
+ * `slip_resistance_dcof`, …). Pass the result in `bySpec`'s `ranges` option.
+ *
+ * BOTH BOUNDS ARE INCLUSIVE — `{ min: 60 }` matches a value of exactly 60 —
+ * because spec language is written that way ("LRV of 60 or more", "DCOF ≥ 0.42")
+ * and because inclusive-both-ends means adjacent ranges overlap at the join
+ * rather than leaving a gap that hides products.
+ *
+ * At least one bound is REQUIRED: a range with neither is a presence check, and
+ * this throws rather than sending a criterion the server would have to refuse.
+ * Discover which attributes take a range — and the span they actually occupy —
+ * from `specificationFacets()`: those are the facets with `kind: "numeric"`.
+ *
+ * @example
+ * // light paints, every brand at once
+ * client.bySpec([], { ranges: [specRangeCriterion("light_reflectance_value", { min: 60 })] });
+ * @example
+ * // a mid-tone band
+ * specRangeCriterion("light_reflectance_value", { min: 30, max: 45 }); // "light_reflectance_value:30..45"
+ */
+export function specRangeCriterion(attributeId, bounds) {
+    const { min, max } = bounds;
+    if (min === undefined && max === undefined) {
+        throw new Error(`specRangeCriterion("${attributeId}") needs a min, a max, or both — a range with neither would match every recorded value. Use hasSpec() for a presence check.`);
+    }
+    if (min !== undefined && max !== undefined && min > max) {
+        throw new Error(`specRangeCriterion("${attributeId}") is inverted (min ${min} > max ${max}) and can only ever match nothing.`);
+    }
+    return `${attributeId}:${min ?? ""}..${max ?? ""}`;
+}
 /**
  * An `attribute:value` criterion string for `bySpec` that filters by
  * certification PROGRAMME across all four certification buckets.

package/sse.js

@@ -40,7 +40,9 @@ export class SseDecoder {
     flush() {
         if (this.#buffer.length > 0) {
             // At end of stream a deferred trailing CR is a real terminator, not data.
-            const line = this.#buffer.endsWith("\r") ? this.#buffer.slice(0, -1) : this.#buffer;
+            const line = this.#buffer.endsWith("\r")
+                ? this.#buffer.slice(0, -1)
+                : this.#buffer;
             this.#buffer = "";
             const frame = this.#consumeLine(line);
             if (frame)

package/suggest-types.js

@@ -21,6 +21,8 @@
  * Undefined members are dropped by the transport.
  */
 export function suggestQuery(q, options) {
-    const kind = Array.isArray(options?.kind) ? options.kind.join(",") : options?.kind;
+    const kind = Array.isArray(options?.kind)
+        ? options.kind.join(",")
+        : options?.kind;
     return { q, limit: options?.limit, kind };
 }