@medicine-wheel/app 0.5.8 → 0.5.10

package/app/api/captures/route.ts

@@ -0,0 +1,224 @@
+import { NextResponse } from "next/server";
+import { z } from "zod";
+import {
+  createProvider,
+  detectProvider,
+  captureRecordId,
+  CAPTURE_KINDS,
+  CAPTURE_ORIGINS,
+  type CaptureFilters,
+} from "@medicine-wheel/storage-provider";
+
+/**
+ * The capture registry's HTTP door: records + URIs only, never bytes. The
+ * bytes stay behind the capture service (@miadi/capture and the gmtermux
+ * edge); this route makes what was captured queryable for chronicle surfaces
+ * such as forgewright episode views.
+ *
+ * `/api/captures` is the CANONICAL path (capture-vocabulary.spec.md §8).
+ * `/api/recordings` remains as a deprecated alias re-exporting these same
+ * handlers — see app/api/recordings/route.ts for the removal condition.
+ */
+
+/** The query params `GET /api/captures` understands. Anything else is a 400. */
+const CAPTURE_FILTER_PARAMS = [
+  "episode_path",
+  "episode_number",
+  "composition",
+  "kind",
+  "origin",
+  "device",
+  "filename",
+] as const;
+
+/**
+ * A silently-ignored filter is the failure this route refuses to repeat from
+ * /api/nodes' history: a consumer that asks `?kinds=audio` and receives a
+ * filtered-looking payload it never filtered has been lied to. An unknown
+ * param is a 400 naming what is accepted, not a shrug.
+ */
+function rejectUnknownParams(searchParams: URLSearchParams) {
+  const unknown = [...new Set(searchParams.keys())].filter(
+    (key) => !(CAPTURE_FILTER_PARAMS as readonly string[]).includes(key),
+  );
+  if (unknown.length === 0) return null;
+
+  return NextResponse.json(
+    {
+      error: `Unknown query parameter${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} — nothing was filtered.`,
+      accepted: [...CAPTURE_FILTER_PARAMS],
+    },
+    { status: 400 },
+  );
+}
+
+/**
+ * Build filters from validated params. A value that cannot mean anything
+ * (`?kind=holograph`, `?episode_number=abc`) is answered with a 400 naming the
+ * accepted values, for the same honesty reason unknown params are.
+ */
+function captureFiltersFromSearchParams(
+  searchParams: URLSearchParams,
+): { filters: CaptureFilters } | { rejection: NextResponse } {
+  const filters: CaptureFilters = {};
+
+  // An empty value means "no filter" — forms submit "" for an unchosen option.
+  const episodePath = searchParams.get("episode_path");
+  const episodeNumber = searchParams.get("episode_number");
+  const composition = searchParams.get("composition");
+  const kind = searchParams.get("kind");
+  const origin = searchParams.get("origin");
+  const device = searchParams.get("device");
+  const filename = searchParams.get("filename");
+
+  if (episodePath) filters.episode_path = episodePath;
+  if (episodeNumber) {
+    const parsed = Number(episodeNumber);
+    if (!Number.isInteger(parsed)) {
+      return {
+        rejection: NextResponse.json(
+          { error: `episode_number must be an integer, got: ${episodeNumber} — nothing was filtered.` },
+          { status: 400 },
+        ),
+      };
+    }
+    filters.episode_number = parsed;
+  }
+  if (composition) filters.composition = composition;
+  if (kind) {
+    if (!(CAPTURE_KINDS as readonly string[]).includes(kind)) {
+      return {
+        rejection: NextResponse.json(
+          {
+            error: `Unknown kind: ${kind} — nothing was filtered.`,
+            accepted: [...CAPTURE_KINDS],
+          },
+          { status: 400 },
+        ),
+      };
+    }
+    filters.kind = kind as CaptureFilters["kind"];
+  }
+  if (origin) {
+    if (!(CAPTURE_ORIGINS as readonly string[]).includes(origin)) {
+      return {
+        rejection: NextResponse.json(
+          {
+            error: `Unknown origin: ${origin} — nothing was filtered.`,
+            accepted: [...CAPTURE_ORIGINS],
+          },
+          { status: 400 },
+        ),
+      };
+    }
+    filters.origin = origin as CaptureFilters["origin"];
+  }
+  if (device) filters.device = device;
+  if (filename) filters.filename = filename;
+
+  return { filters };
+}
+
+const CaptureRegisterSchema = z
+  .object({
+    // Derived from filename (+ episode_path) via captureRecordId when absent.
+    id: z.string().trim().min(1).optional(),
+    filename: z
+      .string({ required_error: "filename is required" })
+      .trim()
+      .min(1, "cannot be empty"),
+    kind: z.enum(CAPTURE_KINDS),
+    origin: z.enum(CAPTURE_ORIGINS),
+    // Where the bytes live — the registry stores this pointer, never bytes.
+    uri: z.string({ required_error: "uri is required" }).trim().min(1, "cannot be empty"),
+    // Capture provenance — observed, not demanded. All optional.
+    device: z.string().optional(),
+    started_at: z.string().optional(),
+    stopped_at: z.string().optional(),
+    duration_seconds: z.number().nonnegative().optional(),
+    bytes: z.number().int().nonnegative().optional(),
+    sha256: z.string().optional(),
+    mimetype: z.string().optional(),
+    // Associations — 0, 1, or 2 belongings; at most declared, never demanded
+    // (capture-vocabulary.spec.md §5). No xor, no refinement: a take with
+    // neither belonging is an inbox take, whole and waiting for a choice.
+    episode_path: z.string().optional(),
+    episode_number: z.number().int().optional(),
+    composition: z.string().optional(),
+    source_artifact: z.string().optional(),
+    registered_at: z.string().optional(),
+    source: z.string().optional(),
+  })
+  // Future fields survive registration, as every sibling family preserves them.
+  .passthrough();
+
+export async function GET(request: Request) {
+  try {
+    const { searchParams } = new URL(request.url);
+
+    const unknownRejection = rejectUnknownParams(searchParams);
+    if (unknownRejection) return unknownRejection;
+
+    const built = captureFiltersFromSearchParams(searchParams);
+    if ("rejection" in built) return built.rejection;
+    const { filters } = built;
+    const filtering = Object.keys(filters).length > 0;
+
+    const store = await createProvider();
+    const captures = await store.listCaptures(filters);
+
+    return NextResponse.json({
+      captures,
+      // DEPRECATED echo of the same array under the old key. forgewright's
+      // fetchRecordingRecords reads `recordings` (or `records`) fail-closed —
+      // a body that only said `captures` would land as silent empty enrichment.
+      // Remove when forgewright's fetchRecordingRecords targets /api/captures
+      // (coupling point, capture-vocabulary.spec.md).
+      recordings: captures,
+      provider: detectProvider(),
+      count: captures.length,
+      // Echoed only when asked for, so a caller can tell an empty result from
+      // an unapplied filter — the same contract /api/nodes keeps.
+      ...(filtering ? { filters } : {}),
+    });
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json().catch(() => null);
+    const parsed = CaptureRegisterSchema.safeParse(body);
+    if (!parsed.success) {
+      return NextResponse.json(
+        {
+          error: "Invalid capture — nothing was registered.",
+          issues: parsed.error.issues.map(
+            (issue) => `${issue.path.join(".") || "body"}: ${issue.message}`,
+          ),
+        },
+        { status: 400 },
+      );
+    }
+
+    const data = parsed.data;
+    const record = {
+      ...data,
+      id: data.id ?? captureRecordId(data.filename, data.episode_path),
+      registered_at: data.registered_at ?? new Date().toISOString(),
+    };
+
+    const store = await createProvider();
+    const capture = await store.registerCapture(record);
+
+    return NextResponse.json(
+      { success: true, capture, provider: detectProvider() },
+      { status: 201 },
+    );
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/app/api/nodes/route.ts

@@ -16,25 +16,93 @@ const NodeCreateSchema = z.object({
   metadata: z.record(z.unknown()).optional(),
 });
 
+/**
+ * The query params `GET /api/nodes` understands. Anything else is a 400.
+ *
+ * Node `type` is a closed enum of six and cannot grow, so every artifact kind
+ * the ecosystem has invented — `chronicle_episode`, `structured_plan`,
+ * `service`, `stc_chart`, `product_goal` — got in through `metadata.kind`
+ * instead, and containment got in through `metadata.parent_id` (31 nodes point
+ * at `chronicle:miadi-chronicle` that way). Both were reachable only by
+ * fetching the whole graph and filtering client-side; forgewright's
+ * `chronicle/client.ts` and this repo's own `HttpStore.searchNodes` each do
+ * exactly that, the latter under the comment "Server has no search endpoint
+ * yet". So the wheel needed no schema change — it needed a way to ask.
+ *
+ * Query params rather than a scoped `/api/nodes/:id/children` route because the
+ * question consumers actually have is "artifacts of kind X belonging to episode
+ * Y", which is `kind` AND `parent_id` together; a scoped route would still need
+ * `?kind=` bolted onto it, and `type`/`direction` already set the query-param
+ * precedent on this same route.
+ */
+const NODE_FILTER_PARAMS = ["type", "direction", "kind", "parent_id"] as const;
+
+/**
+ * A silently-ignored filter is the failure this route exists to prevent: a
+ * consumer that asks `?kinds=service` and gets a filtered-looking payload it
+ * never filtered has been lied to. An unknown param is therefore a 400 naming
+ * what is accepted, not a shrug.
+ */
+function rejectUnknownParams(searchParams: URLSearchParams) {
+  const unknown = [...new Set(searchParams.keys())].filter(
+    (key) => !(NODE_FILTER_PARAMS as readonly string[]).includes(key),
+  );
+  if (unknown.length === 0) return null;
+
+  return NextResponse.json(
+    {
+      error: `Unknown query parameter${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")} — nothing was filtered.`,
+      accepted: [...NODE_FILTER_PARAMS],
+    },
+    { status: 400 },
+  );
+}
+
 export async function GET(request: Request) {
   try {
     const { searchParams } = new URL(request.url);
-    const type = searchParams.get("type");
-    const direction = searchParams.get("direction");
+
+    const rejection = rejectUnknownParams(searchParams);
+    if (rejection) return rejection;
+
+    // An empty value means "no filter" — forms submit "" for an unchosen
+    // option, the same reason POST preprocesses "" on `direction`.
+    const filters = Object.fromEntries(
+      NODE_FILTER_PARAMS.map((key) => [key, searchParams.get(key) || undefined]),
+    ) as Partial<Record<(typeof NODE_FILTER_PARAMS)[number], string>>;
+    const filtering = Object.values(filters).some(Boolean);
 
     const store = await createProvider();
-    let nodes = await store.getAllNodes();
 
-    if (type) {
-      nodes = nodes.filter((n) => n.type === type);
-    } else if (direction) {
-      nodes = nodes.filter((n) => n.direction === direction);
+    // Unfiltered reads keep the provider's own default page size, so this route
+    // answers a bare GET exactly as it always has. A *filtered* read must see
+    // the whole store or it answers from a truncated window — `getAllNodes()`
+    // defaults to 100 and the live wheel already holds 76, so filtering after
+    // the default slice would start returning quietly incomplete sets rather
+    // than failing loudly.
+    let nodes = filtering
+      ? await store.getAllNodes(Number.MAX_SAFE_INTEGER)
+      : await store.getAllNodes();
+
+    // Every supplied filter narrows (AND). Previously `type` and `direction`
+    // were `else if`, so `?type=x&direction=y` silently dropped the direction —
+    // the same silent-ignore defect the 400 above closes. Single-param requests
+    // are unaffected.
+    if (filters.type) nodes = nodes.filter((n) => n.type === filters.type);
+    if (filters.direction) nodes = nodes.filter((n) => n.direction === filters.direction);
+    if (filters.kind) nodes = nodes.filter((n) => n.metadata?.kind === filters.kind);
+    if (filters.parent_id) {
+      nodes = nodes.filter((n) => n.metadata?.parent_id === filters.parent_id);
     }
 
     return NextResponse.json({
       nodes,
       provider: detectProvider(),
-      count: nodes.length
+      count: nodes.length,
+      // Echoed only when asked for, so an unfiltered response stays byte-identical
+      // to what every existing consumer already parses — and so a caller can tell
+      // an empty result from an unapplied filter.
+      ...(filtering ? { filters } : {}),
     });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);

package/app/api/recordings/route.ts

@@ -0,0 +1,14 @@
+/**
+ * DEPRECATED ALIAS — `/api/recordings` answers with the same handlers as the
+ * canonical `/api/captures` route (capture-vocabulary.spec.md §8, the registry
+ * noun ruling).
+ *
+ * This alias is deliberate strangler design, not leftovers: forgewright's
+ * episode-recordings-section branch GETs {MW_API_URL}/api/recordings
+ * fail-closed — on any mismatch it returns silent empty enrichment, and
+ * nothing may fail quiet. The alias keeps that reader fed until it migrates.
+ *
+ * Remove when forgewright's fetchRecordingRecords targets /api/captures
+ * (coupling point, capture-vocabulary.spec.md).
+ */
+export { GET, POST } from "../captures/route";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/app",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "Medicine Wheel — Interactive visual layer for Indigenous relational research with Four Directions, ceremonies, and narrative arcs",
   "bin": {
     "mw": "dist/cli/mw.js",
@@ -85,29 +85,29 @@
     "release:major": "npm run version:major && npm run publish:all && npm run release:commit"
   },
   "dependencies": {
-    "@medicine-wheel/ceremonial-diary": "^0.5.8",
-    "@medicine-wheel/ceremony-protocol": "^0.5.8",
-    "@medicine-wheel/community-review": "^0.5.8",
-    "@medicine-wheel/consent-lifecycle": "^0.5.8",
-    "@medicine-wheel/creative-orientation": "^0.5.8",
-    "@medicine-wheel/data-store": "^0.5.8",
-    "@medicine-wheel/data-store-postgres": "^0.5.8",
-    "@medicine-wheel/fire-keeper": "^0.5.8",
-    "@medicine-wheel/github-ceremony": "^0.5.8",
-    "@medicine-wheel/graph-viz": "^0.5.8",
-    "@medicine-wheel/importance-unit": "^0.5.8",
-    "@medicine-wheel/mcp": "^4.5.8",
-    "@medicine-wheel/narrative-cluster": "^0.5.8",
-    "@medicine-wheel/narrative-engine": "^0.5.8",
-    "@medicine-wheel/ontology-core": "^0.5.8",
-    "@medicine-wheel/perception-layer": "^0.5.8",
-    "@medicine-wheel/prompt-decomposition": "^0.5.8",
-    "@medicine-wheel/relational-index": "^0.5.8",
-    "@medicine-wheel/relational-query": "^0.5.8",
-    "@medicine-wheel/session-reader": "^0.5.8",
-    "@medicine-wheel/storage-provider": "^0.5.8",
-    "@medicine-wheel/transformation-tracker": "^0.5.8",
-    "@medicine-wheel/ui-components": "^0.5.8",
+    "@medicine-wheel/ceremonial-diary": "^0.5.10",
+    "@medicine-wheel/ceremony-protocol": "^0.5.10",
+    "@medicine-wheel/community-review": "^0.5.10",
+    "@medicine-wheel/consent-lifecycle": "^0.5.10",
+    "@medicine-wheel/creative-orientation": "^0.5.10",
+    "@medicine-wheel/data-store": "^0.5.10",
+    "@medicine-wheel/data-store-postgres": "^0.5.10",
+    "@medicine-wheel/fire-keeper": "^0.5.10",
+    "@medicine-wheel/github-ceremony": "^0.5.10",
+    "@medicine-wheel/graph-viz": "^0.5.10",
+    "@medicine-wheel/importance-unit": "^0.5.10",
+    "@medicine-wheel/mcp": "^4.5.10",
+    "@medicine-wheel/narrative-cluster": "^0.5.10",
+    "@medicine-wheel/narrative-engine": "^0.5.10",
+    "@medicine-wheel/ontology-core": "^0.5.10",
+    "@medicine-wheel/perception-layer": "^0.5.10",
+    "@medicine-wheel/prompt-decomposition": "^0.5.10",
+    "@medicine-wheel/relational-index": "^0.5.10",
+    "@medicine-wheel/relational-query": "^0.5.10",
+    "@medicine-wheel/session-reader": "^0.5.10",
+    "@medicine-wheel/storage-provider": "^0.5.10",
+    "@medicine-wheel/transformation-tracker": "^0.5.10",
+    "@medicine-wheel/ui-components": "^0.5.10",
     "@neondatabase/serverless": "^0.10.0",
     "@xyflow/react": "^12.3.0",
     "clsx": "^2.1.1",