Merge pull request #227 from Y33t-dev/backend

feat: add /api/markets, /api/notifications routes, and OpenAPI spec

Author: 1nonlypiece

README.md

@@ -195,6 +195,30 @@ npm run svg
 
 This will automatically convert SVGs to React components in `components/shared/ui/icons/`.
 
+## 🗄️ Backend & API
+
+The server-side API surface is documented in two places:
+
+| Resource | Description |
+|---|---|
+| [`docs/backend-architecture.md`](docs/backend-architecture.md) | Architecture overview — lib/ modules, caching model, security, and how to add a new route |
+| [`openapi.yaml`](openapi.yaml) | OpenAPI 3.1 spec for all `app/api/*` routes, params, and response shapes |
+
+### Available API Routes
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/health` | Public | Platform & Stellar network health |
+| `POST/GET/DELETE` | `/api/auth/session` | — | Session lifecycle |
+| `GET` | `/api/prices` | Public | Asset spot prices (cached 5 s) |
+| `GET` | `/api/markets` | Public | Per-asset supply/borrow APR & utilization (cached 30 s) |
+| `GET` | `/api/positions` | Optional | User lending/borrowing positions |
+| `GET/POST` | `/api/transactions` | Public | Transaction history and creation |
+| `GET` | `/api/transactions/export` | Public | Transactions CSV export |
+| `POST` | `/api/quote` | Public | Lending/borrowing quote calculation |
+| `GET` | `/api/notifications` | Required | List in-app notifications |
+| `PATCH` | `/api/notifications/:id` | Required | Mark notification as read |
+
 ## 🔗 Helpful Links
 
 ### Documentation

app/api/markets/route.ts

@@ -0,0 +1,89 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { globalCache } from '@/lib/cache';
+import { ASSET_SYMBOLS, isAssetSymbol, type AssetSymbol } from '@/types/enums';
+import { fetchMarkets } from '@/lib/markets/repository';
+
+export const runtime = 'nodejs';
+
+/** GET /api/markets
+ *
+ *  Query params:
+ *    asset  – optional, comma-separated AssetSymbol list (e.g. ?asset=XLM,USDC).
+ *             Omit to return all supported assets.
+ *
+ *  Response shape:  MarketsResponse  (see lib/markets/types.ts)
+ *    { markets: AssetMarket[], timestamp: string, source: string }
+ *
+ *  Caching:  public, TTL 30 s / SWR 60 s.
+ *            Bypassed when Authorization header, session cookie, or x-user-id
+ *            header is present (returns X-Cache: BYPASS).
+ *
+ *  Errors:
+ *    400  – unknown asset symbol(s) in the ?asset param
+ *    500  – upstream fetch failure
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const assetParam = searchParams.get('asset') || '';
+
+    // Parse and validate requested assets
+    let assets: AssetSymbol[];
+    if (assetParam) {
+      const requested = assetParam.split(',').map((a) => a.trim().toUpperCase());
+      const invalid = requested.filter((a) => !isAssetSymbol(a));
+      if (invalid.length > 0) {
+        return NextResponse.json(
+          { error: `Unknown asset(s): ${invalid.join(', ')}. Supported: ${ASSET_SYMBOLS.join(', ')}` },
+          { status: 400 },
+        );
+      }
+      assets = requested as AssetSymbol[];
+    } else {
+      assets = [...ASSET_SYMBOLS];
+    }
+
+    // Cache bypass for authenticated requests
+    const authHeader = request.headers.get('Authorization');
+    const hasAuthCookie = request.cookies.has('session') || request.cookies.has('token');
+    const hasUserHeader = request.headers.has('x-user-id');
+    const bypassCache = !!(authHeader || hasAuthCookie || hasUserHeader);
+
+    if (bypassCache) {
+      const data = await fetchMarkets(assets);
+      return NextResponse.json(data, {
+        status: 200,
+        headers: {
+          'Cache-Control': 'no-store, no-cache, must-revalidate, proxy-revalidate',
+          'Pragma': 'no-cache',
+          'Expires': '0',
+          'X-Cache': 'BYPASS',
+        },
+      });
+    }
+
+    // Sort to make the cache key order-invariant (?asset=USDC,XLM == ?asset=XLM,USDC)
+    const cacheKey = `markets:assets:${[...assets].sort().join(',')}`;
+    const cacheOptions = { ttl: 30 * 1000, swr: 60 * 1000 };
+
+    const { value, status } = await globalCache.getOrFetch(
+      cacheKey,
+      () => fetchMarkets(assets),
+      cacheOptions,
+    );
+
+    return NextResponse.json(value, {
+      status: 200,
+      headers: {
+        'Cache-Control': 'public, max-age=30, stale-while-revalidate=60',
+        'X-Cache': status,
+      },
+    });
+  } catch (error) {
+    console.error('Markets route error:', error);
+    return NextResponse.json(
+      { error: 'Failed to fetch market data' },
+      { status: 500 },
+    );
+  }
+}

app/api/notifications/[id]/route.ts

@@ -0,0 +1,44 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { getUser } from '@/lib/auth';
+import { markNotificationRead } from '@/lib/notifications/repository';
+
+export const runtime = 'nodejs';
+
+/** PATCH /api/notifications/:id
+ *
+ *  Marks a notification as read for the authenticated user.
+ *  Requires an authenticated session (session cookie).
+ *
+ *  Route params:
+ *    id  – notification ID (string)
+ *
+ *  Response shape:
+ *    { notification: Notification }
+ *
+ *  Errors:
+ *    400  – missing or blank id
+ *    401  – no valid session
+ *    404  – notification not found for this user
+ */
+export async function PATCH(
+  _req: NextRequest,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const user = await getUser();
+  if (!user) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const { id } = await params;
+
+  if (!id || typeof id !== 'string' || id.trim() === '') {
+    return NextResponse.json({ error: 'Invalid notification id' }, { status: 400 });
+  }
+
+  const notification = markNotificationRead(user.id, id.trim());
+  if (!notification) {
+    return NextResponse.json({ error: 'Notification not found' }, { status: 404 });
+  }
+
+  return NextResponse.json({ notification });
+}

app/api/notifications/route.ts

@@ -0,0 +1,28 @@
+import { NextResponse } from 'next/server';
+import { getUser } from '@/lib/auth';
+import { getNotifications } from '@/lib/notifications/repository';
+
+export const runtime = 'nodejs';
+
+/** GET /api/notifications
+ *
+ *  Requires an authenticated session (session cookie).
+ *  Returns the caller's notifications list and unread count.
+ *
+ *  Response shape:
+ *    { notifications: Notification[], unreadCount: number }
+ *
+ *  Errors:
+ *    401  – no valid session
+ */
+export async function GET() {
+  const user = await getUser();
+  if (!user) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const notifications = getNotifications(user.id);
+  const unreadCount = notifications.filter((n) => !n.read).length;
+
+  return NextResponse.json({ notifications, unreadCount });
+}

app/lending/page.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useState } from 'react';
+import { useState, useEffect } from 'react';
 import LendingForm from '@/components/features/lending/components/LendingForm';
 import BorrowingForm from '@/components/features/lending/components/BorrowingForm';
 import InterestCalculator from '@/components/features/lending/components/InterestCalculator';
@@ -30,6 +30,23 @@ export default function LendingPage() {
   const [calculationResult, setCalculationResult] = useState<CalculationResult | null>(null);
   const [showConfirmModal, setShowConfirmModal] = useState(false);
 
+  // Hydrate default interest rates from the live /api/markets endpoint.
+  // Falls back silently to the hardcoded values above if the fetch fails.
+  useEffect(() => {
+    const controller = new AbortController();
+    fetch('/api/markets?asset=XLM', { signal: controller.signal })
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data: { markets?: Array<{ asset: string; supplyApr: number; borrowApr: number }> } | null) => {
+        if (!data?.markets) return;
+        const xlm = data.markets.find((m) => m.asset === 'XLM');
+        if (!xlm) return;
+        setLendingData((prev) => ({ ...prev, interestRate: xlm.supplyApr }));
+        setBorrowingData((prev) => ({ ...prev, interestRate: xlm.borrowApr }));
+      })
+      .catch(() => { /* keep hardcoded fallback */ });
+    return () => controller.abort();
+  }, []);
+
   const handleLendingSubmit = (data: LendingData) => {
     setLendingData(data);
     setShowConfirmModal(true);