@protoboardai/cloud 0.0.0-stage → 0.2.0

package/src/kits.ts

@@ -0,0 +1,101 @@
+/**
+ * Kit manifests (PB-867): what a purchasable kit contains, item by item,
+ * with the catalog part each item is and how many come in the box. The
+ * library keeps them in `library/kits/<kit>.json` (library/taxonomy.ts reads
+ * and checks them); the seed gives them to the service (`PUT /v1/kits/:kit`)
+ * and the service serves them (`GET /v1/kits`, `GET /v1/kits/:kit`, the
+ * discovery capability `x-kits`).
+ *
+ * A kit is a node of the taxonomy (`kit.<name>`, UHD keeps the node and
+ * leaves the contents to the library that publishes them). Its parts are
+ * filed under that node, so `GET /v1/parts?taxonomy=kit.<name>` finds them;
+ * the manifest adds what search cannot: quantities, the kit's own labels,
+ * series placements and the items that are not catalog parts.
+ *
+ * Pure, and free of `@deltarobotics/uhd` like the rest of the server.
+ */
+
+export interface KitItem {
+  /** The catalog part; absent for an item the catalog does not model. */
+  part_id?: string;
+  /** The ProtoPart part the item came from (the kit was carried over from ProtoPart). */
+  protopart_id?: string;
+  /** The kit's own name for the item (its packing list). */
+  kit_label: string;
+  /** How many come in the kit. */
+  quantity: number;
+  /** Kit contents that are not circuit parts (cables, media, boxes). */
+  unmodeled?: boolean;
+  /** For a series part: the placement (ChildModuleRef overrides). */
+  overrides?: Record<string, unknown>;
+  /** For a series part: the ordering code the placement resolves to. */
+  mpn?: string;
+  note?: string;
+  tutorials?: { title: string; url: string }[];
+}
+
+export interface KitManifest {
+  /** The kit's taxonomy path, `kit.<name>`. */
+  kit: string;
+  name: string;
+  sku?: string;
+  vendor?: string;
+  docs_url?: string;
+  source_url?: string;
+  controller_part_id?: string | null;
+  notes?: string;
+  provenance?: string;
+  items: KitItem[];
+}
+
+/** One row of `GET /v1/kits`. */
+export interface KitSummary {
+  kit: string;
+  name: string;
+  sku?: string;
+  vendor?: string;
+  /** Items in the manifest, and the distinct catalog parts they name. */
+  items: number;
+  parts: number;
+  setAt: string;
+  digest: string;
+}
+
+/** `GET /v1/kits/:kit`: the manifest as given, and the latest revision of each part it names (null: not in the catalog). */
+export interface KitResult {
+  manifest: KitManifest;
+  setAt: string;
+  digest: string;
+  revisions: Record<string, number | null>;
+}
+
+export const KIT_PATH = /^kit\.[a-z][a-z0-9_]*$/;
+
+/** What is wrong with a kit manifest body, as `{ at, message }` problems; empty when it is one. */
+export function kitManifestProblems(body: unknown): { at?: string; message: string }[] {
+  const out: { at?: string; message: string }[] = [];
+  if (!body || typeof body !== "object" || Array.isArray(body)) return [{ message: "the body must be a kit manifest object" }];
+  const k = body as Record<string, unknown>;
+  if (typeof k.kit !== "string" || !KIT_PATH.test(k.kit)) out.push({ at: "kit", message: "kit must be a taxonomy path kit.<name>" });
+  if (typeof k.name !== "string" || !k.name.trim()) out.push({ at: "name", message: "name must be a non-empty string" });
+  for (const f of ["sku", "vendor", "docs_url", "source_url", "notes", "provenance"]) if (k[f] !== undefined && typeof k[f] !== "string") out.push({ at: f, message: `${f} must be a string` });
+  if (k.controller_part_id !== undefined && k.controller_part_id !== null && typeof k.controller_part_id !== "string") out.push({ at: "controller_part_id", message: "controller_part_id must be a part id or null" });
+  if (!Array.isArray(k.items) || !k.items.length) out.push({ at: "items", message: "items must be a non-empty array" });
+  else
+    k.items.forEach((raw, i) => {
+      const it = raw as Record<string, unknown> | null;
+      const at = `items[${i}]`;
+      if (!it || typeof it !== "object" || Array.isArray(it)) return out.push({ at, message: "an item is an object" });
+      if (typeof it.kit_label !== "string" || !it.kit_label.trim()) out.push({ at: `${at}.kit_label`, message: "kit_label must be a non-empty string" });
+      if (!Number.isInteger(it.quantity) || (it.quantity as number) < 1) out.push({ at: `${at}.quantity`, message: "quantity must be an integer >= 1" });
+      if (it.part_id !== undefined && (typeof it.part_id !== "string" || !it.part_id)) out.push({ at: `${at}.part_id`, message: "part_id must be a part id" });
+      if (it.part_id === undefined && it.unmodeled !== true && it.protopart_id === undefined) out.push({ at, message: "an item names a part_id, or is marked unmodeled" });
+      if (it.overrides !== undefined && (typeof it.overrides !== "object" || it.overrides === null || Array.isArray(it.overrides))) out.push({ at: `${at}.overrides`, message: "overrides must be an object" });
+      if (it.overrides !== undefined && it.part_id === undefined) out.push({ at: `${at}.overrides`, message: "overrides place a part: the item needs its part_id" });
+      return undefined;
+    });
+  return out;
+}
+
+/** The catalog parts a manifest names, once each, sorted. */
+export const kitPartIds = (m: KitManifest): string[] => [...new Set(m.items.flatMap((i) => (i.part_id ? [i.part_id] : [])))].sort();

package/src/taxonomy.ts

@@ -0,0 +1,135 @@
+/**
+ * The category taxonomy as the parts service holds it (PB-849). Pure, and
+ * free of `@deltarobotics/uhd` like the rest of the server: the documents
+ * are UHD's taxonomy format (a base taxonomy file and library extensions,
+ * UHD docs/taxonomy.md), which the seed reads from UHD and the library and
+ * sends with `PUT /v1/taxonomy`. test/taxonomy.test.ts checks these helpers
+ * agree with UHD's.
+ *
+ * Parts are indexed by the ancestors of their categories, so a filter on a
+ * path is an exact match and returns the whole subtree.
+ */
+
+export interface TaxonomyNodeData {
+  name: string;
+  description?: string;
+  docs_url?: string;
+  links?: { label: string; url: string }[];
+  agent_notes?: string;
+  kit?: { sku: string; vendor: string; controller_part_id?: string; manifest?: string };
+  children?: Record<string, TaxonomyNodeData>;
+}
+
+/** What the service is given and stores: UHD's taxonomy document and the library's extensions. */
+export interface ServiceTaxonomyDocument {
+  base: { id: string; version: string; delimiter: "."; description?: string; provenance?: Record<string, unknown>; aliases?: Record<string, string[]>; categories: Record<string, TaxonomyNodeData>; $schema?: string };
+  extensions: { library: string; taxonomy: { id: string; version: string }; description?: string; categories?: Record<string, TaxonomyNodeData>; $schema?: string }[];
+}
+
+/** One node of `GET /v1/taxonomy`: parts at or under it in `count`. */
+export interface TaxonomyTreeNode {
+  id: string;
+  path: string;
+  name: string;
+  description?: string;
+  docsUrl?: string;
+  links?: { label: string; url: string }[];
+  agentNotes?: string;
+  kit?: { sku: string; vendor: string; controllerPartId?: string; manifest?: string };
+  /** The taxonomy id ("uhd") or the library of the extension that defines the node. */
+  source: string;
+  count: number;
+  children: TaxonomyTreeNode[];
+}
+
+const DELIM = ".";
+const NODE_ID = /^[a-z][a-z0-9_]*$/;
+const LIBRARY = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SEMVER = /^\d+\.\d+\.\d+$/;
+
+/** Each path and every ancestor of it, once, sorted (UHD `categoryAncestors`). */
+export function categoryAncestors(paths: readonly unknown[] | undefined): string[] {
+  const out = new Set<string>();
+  for (const raw of paths ?? []) {
+    if (typeof raw !== "string") continue;
+    const ids = raw.split(DELIM).filter((s) => s.length > 0);
+    for (let i = 1; i <= ids.length; i++) out.add(ids.slice(0, i).join(DELIM));
+  }
+  return [...out].sort();
+}
+
+const isObject = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+
+/** Shape problems with a taxonomy the service is asked to store (UHD validates the content; this guards the service). */
+export function taxonomyDocumentProblems(doc: unknown): { message: string; at?: string }[] {
+  const out: { message: string; at?: string }[] = [];
+  const nodes = (map: unknown, at: string, root: boolean, library?: string) => {
+    if (!isObject(map)) return void out.push({ message: "must be an object of nodes by id", at });
+    for (const [id, node] of Object.entries(map)) {
+      const okId = root && library !== undefined ? id === `x-${library}` : NODE_ID.test(id);
+      if (!okId) out.push({ message: library !== undefined && root ? `extension root must be x-${library}` : `node id "${id}" is not a lower-case id`, at });
+      if (!isObject(node) || typeof node.name !== "string" || node.name === "") out.push({ message: "a node needs a name", at: `${at}.${id}` });
+      else if (node.children !== undefined) nodes(node.children, `${at}.${id}.children`, false);
+    }
+  };
+  if (!isObject(doc)) return [{ message: "body must be { base, extensions }" }];
+  const base = doc.base;
+  if (!isObject(base) || typeof base.id !== "string" || typeof base.version !== "string" || !SEMVER.test(base.version) || base.delimiter !== DELIM)
+    out.push({ message: "base must be a taxonomy document with id, version (MAJOR.MINOR.PATCH) and delimiter \".\"", at: "base" });
+  else nodes(base.categories, "base.categories", true);
+  if (!Array.isArray(doc.extensions)) out.push({ message: "extensions must be an array", at: "extensions" });
+  else
+    doc.extensions.forEach((e, i) => {
+      if (!isObject(e) || typeof e.library !== "string" || !LIBRARY.test(e.library) || !isObject(e.taxonomy)) return void out.push({ message: "an extension needs library and taxonomy { id, version }", at: `extensions[${i}]` });
+      if (e.categories !== undefined) nodes(e.categories, `extensions[${i}].categories`, true, e.library);
+    });
+  return out;
+}
+
+/** Every node path the document defines. */
+export function taxonomyPaths(doc: ServiceTaxonomyDocument): Set<string> {
+  const out = new Set<string>();
+  const walk = (map: Record<string, TaxonomyNodeData> | undefined, prefix: string) => {
+    for (const [id, n] of Object.entries(map ?? {})) {
+      const path = prefix ? `${prefix}${DELIM}${id}` : id;
+      out.add(path);
+      walk(n.children, path);
+    }
+  };
+  walk(doc.base.categories, "");
+  for (const e of doc.extensions) walk(e.categories, "");
+  return out;
+}
+
+/** The tree with each node's count (UHD `taxonomyTree`, with every count present). */
+export function taxonomyTreeWithCounts(doc: ServiceTaxonomyDocument, counts: ReadonlyMap<string, number>): TaxonomyTreeNode[] {
+  const convert = (id: string, n: TaxonomyNodeData, prefix: string, source: string): TaxonomyTreeNode => {
+    const path = prefix ? `${prefix}${DELIM}${id}` : id;
+    return {
+      id,
+      path,
+      name: n.name,
+      ...(n.description !== undefined ? { description: n.description } : {}),
+      ...(n.docs_url !== undefined ? { docsUrl: n.docs_url } : {}),
+      ...(n.links?.length ? { links: n.links.map((l) => ({ label: l.label, url: l.url })) } : {}),
+      ...(n.agent_notes !== undefined ? { agentNotes: n.agent_notes } : {}),
+      ...(n.kit
+        ? {
+            kit: {
+              sku: n.kit.sku,
+              vendor: n.kit.vendor,
+              ...(n.kit.controller_part_id !== undefined ? { controllerPartId: n.kit.controller_part_id } : {}),
+              ...(n.kit.manifest !== undefined ? { manifest: n.kit.manifest } : {}),
+            },
+          }
+        : {}),
+      source,
+      count: counts.get(path) ?? 0,
+      children: Object.entries(n.children ?? {}).map(([cid, c]) => convert(cid, c, path, source)),
+    };
+  };
+  return [
+    ...Object.entries(doc.base.categories).map(([id, n]) => convert(id, n, "", doc.base.id)),
+    ...doc.extensions.flatMap((e) => Object.entries(e.categories ?? {}).map(([id, n]) => convert(id, n, "", e.library))),
+  ];
+}