Merge pull request #515 from trails-cool/domain-type-unification

One source of truth for Route/Activity shapes; enforce api contracts at the seam

apps/journal/app/lib/api-guard.server.ts

@@ -1,3 +1,4 @@
+import type { z } from "zod";
 import { getAuthenticatedUser } from "./oauth.server.ts";
 import { TERMS_VERSION } from "./legal.ts";
 import { ERROR_CODES } from "@trails-cool/api";
@@ -36,3 +37,19 @@ export async function requireApiUser(request: Request) {
 export function apiError(status: number, code: string, message: string, fields?: Array<{ field: string; message: string }>) {
   return Response.json({ error: message, code, fields }, { status });
 }
+
+/**
+ * Respond with a payload validated against its @trails-cool/api
+ * contract. The schema is enforced, not advisory: a handler whose
+ * payload drifts from the contract fails its unit tests / e2e run with
+ * a ZodError instead of silently shipping a different wire shape.
+ * Parsing also strips unknown keys, so the response is exactly the
+ * contract — nothing extra leaks.
+ */
+export function apiJson<S extends z.ZodType>(
+  schema: S,
+  payload: z.input<S>,
+  init?: ResponseInit,
+): Response {
+  return Response.json(schema.parse(payload), init);
+}

apps/journal/app/routes/api.v1.activities.$id.ts

@@ -1,8 +1,8 @@
 import type { Route } from "./+types/api.v1.activities.$id";
-import { requireApiUser, apiError } from "~/lib/api-guard.server";
+import { requireApiUser, apiError, apiJson } from "~/lib/api-guard.server";
 import { getActivity, deleteActivity } from "~/lib/activities.server";
 import { loadOwnedActivity } from "~/lib/ownership.server";
-import { ERROR_CODES } from "@trails-cool/api";
+import { ERROR_CODES, ActivityDetailSchema } from "@trails-cool/api";
 
 /** GET /api/v1/activities/:id — full activity detail */
 export async function loader({ request, params }: Route.LoaderArgs) {
@@ -13,11 +13,14 @@ export async function loader({ request, params }: Route.LoaderArgs) {
     return apiError(404, ERROR_CODES.NOT_FOUND, "Activity not found");
   }
 
-  return Response.json({
+  return apiJson(ActivityDetailSchema, {
     id: activity.id,
     name: activity.name,
-    description: activity.description,
+    description: activity.description ?? "",
     routeId: activity.routeId,
+    routeName: null, // TODO: join route name (matches the list endpoint)
+    photos: [], // no photos on this surface yet; contract field
+
     distance: activity.distance,
     duration: activity.duration,
     elevationGain: activity.elevationGain,

apps/journal/app/routes/api.v1.activities._index.ts

@@ -1,11 +1,13 @@
 import type { Route } from "./+types/api.v1.activities._index";
-import { requireApiUser, apiError } from "~/lib/api-guard.server";
+import { requireApiUser, apiError, apiJson } from "~/lib/api-guard.server";
 import { listActivities, createActivity } from "~/lib/activities.server";
 import {
   PaginationQuerySchema,
   CreateActivityRequestSchema,
   ERROR_CODES,
   zodIssuesToFieldErrors,
+  ActivityListResponseSchema,
+  CreateActivityResponseSchema,
 } from "@trails-cool/api";
 
 /** GET /api/v1/activities — paginated activity list */
@@ -32,11 +34,11 @@ export async function loader({ request }: Route.LoaderArgs) {
   const page = allActivities.slice(startIdx, startIdx + limit);
   const nextCursor = startIdx + limit < allActivities.length ? page[page.length - 1]?.id ?? null : null;
 
-  return Response.json({
+  return apiJson(ActivityListResponseSchema, {
     activities: page.map((a) => ({
       id: a.id,
       name: a.name,
-      description: a.description,
+      description: a.description ?? "",
       routeId: a.routeId,
       routeName: null, // TODO: join route name
       distance: a.distance,
@@ -67,5 +69,5 @@ export async function action({ request }: Route.ActionArgs) {
     ...parsed.data,
     startedAt: parsed.data.startedAt ? new Date(parsed.data.startedAt) : null,
   });
-  return Response.json({ id }, { status: 201 });
+  return apiJson(CreateActivityResponseSchema, { id }, { status: 201 });
 }

apps/journal/app/routes/api.v1.routes.$id.ts

@@ -1,8 +1,8 @@
 import type { Route } from "./+types/api.v1.routes.$id";
-import { requireApiUser, apiError } from "~/lib/api-guard.server";
+import { requireApiUser, apiError, apiJson } from "~/lib/api-guard.server";
 import { getRouteWithVersions, updateRoute, deleteRoute } from "~/lib/routes.server";
 import { loadOwnedRoute } from "~/lib/ownership.server";
-import { UpdateRouteRequestSchema, ERROR_CODES, zodIssuesToFieldErrors } from "@trails-cool/api";
+import { UpdateRouteRequestSchema, ERROR_CODES, zodIssuesToFieldErrors, RouteDetailSchema } from "@trails-cool/api";
 
 /** GET /api/v1/routes/:id — full route detail */
 export async function loader({ request, params }: Route.LoaderArgs) {
@@ -13,10 +13,10 @@ export async function loader({ request, params }: Route.LoaderArgs) {
     return apiError(404, ERROR_CODES.NOT_FOUND, "Route not found");
   }
 
-  return Response.json({
+  return apiJson(RouteDetailSchema, {
     id: route.id,
     name: route.name,
-    description: route.description,
+    description: route.description ?? "",
     distance: route.distance,
     elevationGain: route.elevationGain,
     elevationLoss: route.elevationLoss,

apps/journal/app/routes/api.v1.routes._index.ts

@@ -1,11 +1,13 @@
 import type { Route } from "./+types/api.v1.routes._index";
-import { requireApiUser, apiError } from "~/lib/api-guard.server";
+import { requireApiUser, apiError, apiJson } from "~/lib/api-guard.server";
 import { listRoutes, createRoute } from "~/lib/routes.server";
 import {
   PaginationQuerySchema,
   CreateRouteRequestSchema,
   ERROR_CODES,
   zodIssuesToFieldErrors,
+  RouteListResponseSchema,
+  CreateRouteResponseSchema,
 } from "@trails-cool/api";
 
 /** GET /api/v1/routes — paginated route list */
@@ -32,11 +34,11 @@ export async function loader({ request }: Route.LoaderArgs) {
   const page = allRoutes.slice(startIdx, startIdx + limit);
   const nextCursor = startIdx + limit < allRoutes.length ? page[page.length - 1]?.id ?? null : null;
 
-  return Response.json({
+  return apiJson(RouteListResponseSchema, {
     routes: page.map((r) => ({
       id: r.id,
       name: r.name,
-      description: r.description,
+      description: r.description ?? "",
       distance: r.distance,
       elevationGain: r.elevationGain,
       elevationLoss: r.elevationLoss,
@@ -63,5 +65,5 @@ export async function action({ request }: Route.ActionArgs) {
   }
 
   const id = await createRoute(user.id, parsed.data);
-  return Response.json({ id }, { status: 201 });
+  return apiJson(CreateRouteResponseSchema, { id }, { status: 201 });
 }

apps/journal/app/routes/api.v1.routes.test.ts

@@ -3,6 +3,9 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { TERMS_VERSION } from "~/lib/legal";
 
 const mockUser = { id: "user-1", email: "test@test.com", username: "test", domain: "localhost", displayName: null, bio: null, createdAt: new Date(), termsVersion: TERMS_VERSION };
+const ROUTE_ID = "11111111-1111-4111-8111-111111111111";
+const VERSION_ID = "22222222-2222-4222-8222-222222222222";
+const NEW_ID = "33333333-3333-4333-8333-333333333333";
 const mockGetAuthenticatedUser = vi.fn();
 const mockListRoutes = vi.fn();
 const mockCreateRoute = vi.fn();
@@ -51,7 +54,7 @@ describe("GET /api/v1/routes", () => {
     const now = new Date();
     mockListRoutes.mockResolvedValue([
       {
-        id: "r1", name: "Tour", description: "", distance: 42000,
+        id: ROUTE_ID, name: "Tour", description: "", distance: 42000,
         elevationGain: 340, elevationLoss: 320, routingProfile: "fastbike",
         dayBreaks: [], geojson: null, ownerId: "user-1", gpx: null,
         tags: null, plannerState: null, createdAt: now, updatedAt: now,
@@ -63,7 +66,7 @@ describe("GET /api/v1/routes", () => {
     const data = await resp.json();
 
     expect(data.routes).toHaveLength(1);
-    expect(data.routes[0].id).toBe("r1");
+    expect(data.routes[0].id).toBe(ROUTE_ID);
     expect(data.nextCursor).toBeNull();
   });
 
@@ -83,7 +86,7 @@ describe("GET /api/v1/routes", () => {
 
 describe("POST /api/v1/routes", () => {
   it("creates a route with valid body", async () => {
-    mockCreateRoute.mockResolvedValue("new-id");
+    mockCreateRoute.mockResolvedValue(NEW_ID);
     const { action } = await import("./api.v1.routes._index.ts");
 
     const resp = await action(routeArgs(
@@ -95,7 +98,7 @@ describe("POST /api/v1/routes", () => {
 
     expect(resp.status).toBe(201);
     const data = await resp.json();
-    expect(data.id).toBe("new-id");
+    expect(data.id).toBe(NEW_ID);
   });
 
   it("returns 400 on validation error", async () => {
@@ -117,20 +120,20 @@ describe("GET /api/v1/routes/:id", () => {
   it("returns route detail", async () => {
     const now = new Date();
     mockGetRouteWithVersions.mockResolvedValue({
-      id: "r1", name: "Tour", description: "", distance: 42000,
+      id: ROUTE_ID, name: "Tour", description: "", distance: 42000,
       elevationGain: 340, elevationLoss: 320, routingProfile: "fastbike",
       dayBreaks: [], gpx: "<gpx/>", ownerId: "user-1",
       tags: null, plannerState: null, createdAt: now, updatedAt: now,
-      versions: [{ id: "v1", routeId: "r1", version: 1, gpx: "<gpx/>", createdBy: "user-1", changeDescription: null, createdAt: now }],
+      versions: [{ id: VERSION_ID, routeId: ROUTE_ID, version: 1, gpx: "<gpx/>", createdBy: "user-1", changeDescription: null, createdAt: now }],
     });
 
     const { loader } = await import("./api.v1.routes.$id.ts");
     const resp = await loader(routeArgs(
-      authRequest("/api/v1/routes/r1"), { id: "r1" }, "api/v1/routes/:id",
+      authRequest(`/api/v1/routes/${ROUTE_ID}`), { id: ROUTE_ID }, "api/v1/routes/:id",
     )) as Response;
 
     const data = await resp.json();
-    expect(data.id).toBe("r1");
+    expect(data.id).toBe(ROUTE_ID);
     expect(data.gpx).toBe("<gpx/>");
     expect(data.versions).toHaveLength(1);
   });

packages/api/src/activities.ts

@@ -39,7 +39,11 @@ export const CreateActivityRequestSchema = z.object({
   distance: z.number().optional(),
 });
 
+/** Response to POST /api/v1/activities */
+export const CreateActivityResponseSchema = z.object({ id: z.uuid() });
+
 export type ActivitySummary = z.infer<typeof ActivitySummarySchema>;
+export type CreateActivityResponse = z.infer<typeof CreateActivityResponseSchema>;
 export type ActivityDetail = z.infer<typeof ActivityDetailSchema>;
 export type ActivityListResponse = z.infer<typeof ActivityListResponseSchema>;
 export type CreateActivityRequest = z.infer<typeof CreateActivityRequestSchema>;

packages/api/src/index.ts

@@ -33,10 +33,12 @@ export {
   RouteSummarySchema, RouteDetailSchema, RouteVersionSchema,
   RouteListResponseSchema,
   CreateRouteRequestSchema, UpdateRouteRequestSchema,
+  CreateRouteResponseSchema,
   ComputeRouteRequestSchema,
   type RouteSummary, type RouteDetail, type RouteVersion,
   type RouteListResponse,
   type CreateRouteRequest, type UpdateRouteRequest,
+  type CreateRouteResponse,
   type ComputeRouteRequest,
 } from "./routes.ts";
 
@@ -44,10 +46,10 @@ export {
 export {
   ActivitySummarySchema, ActivityDetailSchema,
   ActivityListResponseSchema,
-  CreateActivityRequestSchema,
+  CreateActivityRequestSchema, CreateActivityResponseSchema,
   type ActivitySummary, type ActivityDetail,
   type ActivityListResponse,
-  type CreateActivityRequest,
+  type CreateActivityRequest, type CreateActivityResponse,
 } from "./activities.ts";
 
 // Uploads

packages/api/src/routes.ts

@@ -17,7 +17,9 @@ export const RouteSummarySchema = z.object({
 
 /** Route version info */
 export const RouteVersionSchema = z.object({
+  id: z.uuid(),
   version: z.number(),
+  createdBy: z.string().nullable(),
   changeDescription: z.string().nullable(),
   createdAt: z.iso.datetime(),
 });
@@ -64,7 +66,11 @@ export const ComputeRouteRequestSchema = z.object({
   })).optional(),
 });
 
+/** Response to POST /api/v1/routes */
+export const CreateRouteResponseSchema = z.object({ id: z.uuid() });
+
 export type RouteSummary = z.infer<typeof RouteSummarySchema>;
+export type CreateRouteResponse = z.infer<typeof CreateRouteResponseSchema>;
 export type RouteVersion = z.infer<typeof RouteVersionSchema>;
 export type RouteDetail = z.infer<typeof RouteDetailSchema>;
 export type RouteListResponse = z.infer<typeof RouteListResponseSchema>;

packages/db/src/schema/journal.ts

@@ -463,3 +463,13 @@ export const consumedJwtJti = journalSchema.table("consumed_jwt_jti", {
   // Sweep runs `DELETE WHERE expires_at < now()` on a daily schedule.
   expiresAtIdx: index("consumed_jwt_jti_expires_at_idx").on(t.expiresAt),
 }));
+
+// ---------------------------------------------------------------------------
+// Canonical row types — derive from the schema, never re-declare by hand.
+// API wire shapes live in @trails-cool/api; these are the database truth.
+// ---------------------------------------------------------------------------
+
+export type RouteRow = typeof routes.$inferSelect;
+export type RouteVersionRow = typeof routeVersions.$inferSelect;
+export type ActivityRow = typeof activities.$inferSelect;
+export type UserRow = typeof users.$inferSelect;

packages/types/src/index.ts

@@ -1,7 +1,13 @@
 /**
- * Shared TypeScript types for trails.cool
+ * Shared TypeScript types for trails.cool — the Waypoint wire format
+ * used by both the Planner and Journal apps (Yjs document, GPX
+ * extensions, handoff payloads).
  *
- * These types are used by both the Planner and Journal apps.
+ * Not here on purpose: database row types are derived from the Drizzle
+ * schema (@trails-cool/db, e.g. RouteRow), and API response shapes are
+ * the Zod contracts in @trails-cool/api. Earlier hand-written Route /
+ * Activity interfaces in this file drifted from both and had zero
+ * importers when they were removed.
  */
 
 export interface WaypointPoiTags {
@@ -26,48 +32,3 @@ export interface Waypoint {
   osmId?: number;
   poiTags?: WaypointPoiTags;
 }
-
-export interface RouteMetadata {
-  created: Date;
-  updated: Date;
-  owner: string;
-  contributors: string[];
-  routingProfile: string;
-  dayBreaks: number[];
-  distance: number;
-  elevation: {
-    gain: number;
-    loss: number;
-  };
-  tags: string[];
-}
-
-export interface Route {
-  id: string;
-  name: string;
-  description: string;
-  gpx: string;
-  metadata: RouteMetadata;
-  plannerState?: Uint8Array;
-  versions: RouteVersion[];
-}
-
-export interface RouteVersion {
-  version: number;
-  gpx: string;
-  createdAt: Date;
-  createdBy: string;
-  changeDescription?: string;
-}
-
-export interface Activity {
-  id: string;
-  routeId?: string;
-  name: string;
-  description: string;
-  gpx: string;
-  startedAt: Date;
-  duration: number;
-  photos: string[];
-  participants: string[];
-}