✨ feat: implement new API layer with request deduplication, caching, and Sentry integration

frontend/src/lib/api.ts

@@ -0,0 +1,198 @@
+/**
+ * API Layer
+ *
+ * Modern fetch-based API layer with:
+ * - Request deduplication (identical concurrent GETs share one promise)
+ * - Loading indicator integration (requestsStore)
+ * - AbortSignal support
+ * - Build-version checking (X-Build-Time header)
+ * - Sentry span instrumentation
+ * - In-memory cache for getCachedEntries / getCachedEntry
+ */
+import { get } from "svelte/store"
+import { apiRequest, obj2str } from "../../../api/hooks/lib/ssr"
+import * as sentry from "../sentry"
+import { apiBaseOverride } from "./store"
+import { incrementRequests, decrementRequests } from "./requestsStore"
+import { setServerBuildTime } from "./serverBuildInfo"
+import { checkBuildVersion } from "./versionCheck"
+
+// ---------------------------------------------------------------------------
+// Request deduplication
+// ---------------------------------------------------------------------------
+const pendingRequests = new Map<string, Promise<any>>()
+
+/**
+ * Generate a deterministic cache key for a request so identical parallel calls
+ * collapse into a single network round-trip.
+ */
+const getRequestCacheKey = (endpoint: string, options?: ApiOptions, body?: any): string => {
+    const deterministicStringify = (obj: any): string => {
+        if (obj === null || obj === undefined) return String(obj)
+        if (typeof obj !== "object") return JSON.stringify(obj)
+        if (Array.isArray(obj)) return `[${obj.map(deterministicStringify).join(",")}]`
+        const keys = Object.keys(obj).sort()
+        const pairs = keys.map((key) => `${JSON.stringify(key)}:${deterministicStringify(obj[key])}`)
+        return `{${pairs.join(",")}}`
+    }
+    return deterministicStringify({ endpoint, options, body })
+}
+
+// ---------------------------------------------------------------------------
+// Core API function
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute an API request.
+ *
+ * - Identical concurrent GET requests are deduplicated automatically.
+ * - Pass `signal` to opt-out of deduplication and enable cancellation.
+ * - Drives the global loading indicator via `requestsStore`.
+ * - Reads the `X-Build-Time` response header and triggers version check.
+ *
+ * @example
+ * const { data, count } = await api<ContentEntry[]>("content", { filter: { lang: "de" } })
+ */
+export const api = async <T>(
+    endpoint: string,
+    options?: ApiOptions,
+    body?: any,
+    signal?: AbortSignal
+): Promise<ApiResult<T>> => {
+    const _apiBaseOverride = get(apiBaseOverride) || ""
+
+    // Merge options – auth header injection can be added here later:
+    // const authToken = getAccessToken()
+    // ...(authToken ? { Authorization: `Bearer ${authToken}` } : {})
+    const mergedHeaders = {
+        ...(options?.headers || {}),
+    }
+    const mergedOptions: ApiOptions = { ...options, headers: mergedHeaders, signal }
+
+    // Deduplication: skip when caller provides a signal (they want explicit control)
+    const cacheKey = getRequestCacheKey(endpoint, options, body)
+    if (!signal && pendingRequests.has(cacheKey)) {
+        return pendingRequests.get(cacheKey)!
+    }
+
+    const requestPromise = (async () => {
+        try {
+            if (signal?.aborted) {
+                throw new DOMException("Aborted", "AbortError")
+            }
+            incrementRequests()
+
+            const data = await apiRequest(_apiBaseOverride + endpoint, mergedOptions, body, sentry)
+
+            // Build-version check only on GETs (don't reload mid-write)
+            const method = mergedOptions?.method?.toUpperCase() || "GET"
+            if (method === "GET" && data?.buildTime) {
+                setServerBuildTime(data.buildTime)
+                checkBuildVersion(data.buildTime)
+            }
+
+            return data as ApiResult<T>
+        } catch (err) {
+            // Don't send abort errors to Sentry
+            if ((err as any)?.name === "AbortError") throw err
+
+            // Auth: 401 handling placeholder
+            // const status = (err as any)?.response?.status
+            // if (status === 401) { /* refresh token + retry */ }
+
+            throw err
+        } finally {
+            if (!signal) {
+                pendingRequests.delete(cacheKey)
+            }
+            decrementRequests()
+        }
+    })()
+
+    if (!signal) {
+        pendingRequests.set(cacheKey, requestPromise)
+    }
+
+    return requestPromise
+}
+
+// ---------------------------------------------------------------------------
+// In-memory response cache (for getCachedEntries / getCachedEntry)
+// ---------------------------------------------------------------------------
+const cache: { [key: string]: { expire: number; data: any } } = {}
+const CACHE_TTL = 1000 * 60 * 60 // 1 hour
+
+// ---------------------------------------------------------------------------
+// Generic collection helpers
+// ---------------------------------------------------------------------------
+
+type CollectionNameT = "medialib" | "content" | string
+
+type EntryTypeSwitch<T extends string> = T extends "medialib"
+    ? MedialibEntry
+    : T extends "content"
+      ? ContentEntry
+      : Record<string, any>
+
+export async function getDBEntries<T extends CollectionNameT>(
+    collectionName: T,
+    filter?: { [key: string]: any },
+    sort: string = "sort",
+    limit?: number,
+    offset?: number,
+    projection?: string,
+    params?: { [key: string]: string }
+): Promise<EntryTypeSwitch<T>[]> {
+    const c = await api<EntryTypeSwitch<T>[]>(collectionName, {
+        filter,
+        sort,
+        limit,
+        offset,
+        projection,
+        params,
+    })
+    return c.data
+}
+
+export async function getCachedEntries<T extends CollectionNameT>(
+    collectionName: T,
+    filter?: { [key: string]: any },
+    sort: string = "sort",
+    limit?: number,
+    offset?: number,
+    projection?: string,
+    params?: { [key: string]: string }
+): Promise<EntryTypeSwitch<T>[]> {
+    const filterStr = obj2str({ collectionName, filter, sort, limit, offset, projection, params })
+    if (cache[filterStr] && cache[filterStr].expire >= Date.now()) {
+        return cache[filterStr].data
+    }
+    const entries = await getDBEntries<T>(collectionName, filter, sort, limit, offset, projection, params)
+    cache[filterStr] = { expire: Date.now() + CACHE_TTL, data: entries }
+    return entries
+}
+
+export async function getDBEntry<T extends CollectionNameT>(
+    collectionName: T,
+    filter: { [key: string]: any },
+    projection?: string,
+    params?: { [key: string]: string }
+) {
+    return (await getDBEntries<T>(collectionName, filter, "_id", 1, null, projection, params))?.[0]
+}
+
+export async function getCachedEntry<T extends CollectionNameT>(
+    collectionName: T,
+    filter: { [key: string]: any },
+    projection?: string,
+    params?: { [key: string]: string }
+) {
+    return (await getCachedEntries<T>(collectionName, filter, "_id", 1, null, projection, params))?.[0]
+}
+
+export async function postDBEntry<T extends CollectionNameT>(
+    collectionName: T,
+    entry: EntryTypeSwitch<T>
+): Promise<ApiResult<EntryTypeSwitch<T>>> {
+    return api<EntryTypeSwitch<T>>(collectionName, { method: "POST" }, entry)
+}