Add utility lookup by EIA ID

Adds GET /api/v1/utilities/by-eia-id/{eiaId}, a sibling to the existing
slug-based detail route for consumers that hold canonical EIA Utility IDs.

The new route mirrors the slug route response shape and supports the same
?include=iso,rto,ba and ?fields sparse-fieldset semantics. It excludes
soft-deleted utilities and returns a normal public API 404 when no matching
EIA ID exists.

Also adds shared edge caching headers to utility detail responses:
public, s-maxage=3600, stale-while-revalidate=86400.

Validation: npm run build includes /api/v1/utilities/by-eia-id/[eiaId].

Author: texture-coding-agent

app/api/v1/utilities/[slug]/route.ts

@@ -11,6 +11,8 @@ import { balancingAuthorities, isos, rtos, utilities } from "@/lib/db/schema";
 // GET /api/v1/utilities/[slug] — Get utility by slug with optional includes
 // ---------------------------------------------------------------------------
 
+const CACHE_CONTROL = "public, s-maxage=3600, stale-while-revalidate=86400";
+
 async function handleGet(req: Request, ctx: RouteContext) {
   const slug = ctx.params?.slug;
   if (!slug) {
@@ -72,10 +74,10 @@ async function handleGet(req: Request, ctx: RouteContext) {
     }
 
     await Promise.all(fetches);
-    return publicJsonResponse(result, 200, {}, { fields });
+    return publicJsonResponse(result, 200, { "Cache-Control": CACHE_CONTROL }, { fields });
   }
 
-  return publicJsonResponse(utility, 200, {}, { fields });
+  return publicJsonResponse(utility, 200, { "Cache-Control": CACHE_CONTROL }, { fields });
 }
 
 const handler = withRequestId(withErrorHandling(withTiming(handleGet)));

app/api/v1/utilities/by-eia-id/[eiaId]/route.ts

@@ -0,0 +1,107 @@
+import { and, eq, isNull } from "drizzle-orm";
+import type { NextRequest } from "next/server";
+import { ApiError } from "@/lib/api/errors";
+import { generateRequestId, withErrorHandling, withRequestId, withTiming } from "@/lib/api/middleware";
+import { publicJsonResponse } from "@/lib/api/public-response";
+import type { RouteContext } from "@/lib/api/types";
+import { getDb } from "@/lib/db/client";
+import { balancingAuthorities, isos, rtos, utilities } from "@/lib/db/schema";
+
+// ---------------------------------------------------------------------------
+// GET /api/v1/utilities/by-eia-id/[eiaId] — Get utility by EIA Utility ID
+//
+// Sibling route to /api/v1/utilities/[slug]. Some consumers (especially
+// server-to-server integrations that hold the canonical EIA ID rather than
+// the Texture slug) find the slug route awkward; this route lets them look
+// up the same record via the numeric-ish EIA ID directly.
+//
+// Identical response shape and ?include=iso,rto,ba / ?fields semantics to
+// the slug route.
+// ---------------------------------------------------------------------------
+
+// Edge caching: utility records change at most a few times a year per row
+// (EIA Form 861 annual update, occasional admin edits). A 1 hour shared-
+// maxage with 24 hour SWR is generous enough for DataLoader-batched fan-out
+// from downstream consumers to be effectively free at steady state, while
+// still reflecting admin edits within the hour. Matches the slug route.
+const CACHE_CONTROL = "public, s-maxage=3600, stale-while-revalidate=86400";
+
+async function handleGet(req: Request, ctx: RouteContext) {
+  const eiaId = ctx.params?.eiaId;
+  if (!eiaId) {
+    throw new ApiError("BAD_REQUEST", "Missing eiaId parameter");
+  }
+
+  const url = new URL(req.url);
+  const include = url.searchParams.get("include");
+  const fields = url.searchParams.get("fields");
+
+  const db = getDb();
+  const [utility] = await db
+    .select()
+    .from(utilities)
+    .where(and(eq(utilities.eiaId, eiaId), isNull(utilities.deletedAt)))
+    .limit(1);
+
+  if (!utility) {
+    throw new ApiError("NOT_FOUND", `Utility with EIA ID '${eiaId}' not found`);
+  }
+
+  const headers = { "Cache-Control": CACHE_CONTROL };
+
+  if (include) {
+    const includes = include.split(",").map((i) => i.trim());
+    const result: Record<string, unknown> = { ...utility };
+
+    const fetches: Promise<void>[] = [];
+
+    if (includes.includes("iso") && utility.isoId) {
+      fetches.push(
+        db
+          .select()
+          .from(isos)
+          .where(eq(isos.id, utility.isoId))
+          .limit(1)
+          .then(([iso]) => {
+            result._iso = iso ?? null;
+          })
+      );
+    }
+    if (includes.includes("rto") && utility.rtoId) {
+      fetches.push(
+        db
+          .select()
+          .from(rtos)
+          .where(eq(rtos.id, utility.rtoId))
+          .limit(1)
+          .then(([rto]) => {
+            result._rto = rto ?? null;
+          })
+      );
+    }
+    if (includes.includes("ba") && utility.balancingAuthorityId) {
+      fetches.push(
+        db
+          .select()
+          .from(balancingAuthorities)
+          .where(eq(balancingAuthorities.id, utility.balancingAuthorityId))
+          .limit(1)
+          .then(([ba]) => {
+            result._ba = ba ?? null;
+          })
+      );
+    }
+
+    await Promise.all(fetches);
+    return publicJsonResponse(result, 200, headers, { fields });
+  }
+
+  return publicJsonResponse(utility, 200, headers, { fields });
+}
+
+const handler = withRequestId(withErrorHandling(withTiming(handleGet)));
+
+export async function GET(req: NextRequest, { params }: { params: Promise<{ eiaId: string }> }) {
+  const { eiaId } = await params;
+  return handler(req, { params: { eiaId }, requestId: generateRequestId() });
+}