Files
crosscode-platform/apps/events/frontend/src/lib/api.ts
T
joshuaandClaude Opus 5.5 91047bcde2 Express 5, scanner on API v2, v1 deprecation headers (1.51.3)
- Express 5 (qs query parser and req.body = {} kept as in Express 4).
- Scanner and at-the-door check-in use /api/v2/checkin; look-up gives attendee, bookedBy,
  ticketOptionId.
- Shared middleware errors on /api/v2 rewritten to { error: { code, message, reason } };
  apiFetch treats reason like v1's code.
- Deprecation + Link: rel="successor-version" on v1 endpoints that have a v2 replacement.
- Roadmap: open question on how much of v1 to retire in 2.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ls1vMdg2GYqbnKZmPaX1ot
2026-10-29 09:46:24 +02:00

228 lines
9.8 KiB
TypeScript

import type { Paginated, Payment, User } from "@/types";
export type ApiOptions = {
method?: string;
headers?: Record<string, string>;
body?: unknown;
authToken?: string | null;
nextOptions?: RequestInit;
};
// Compute a robust API base that works locally, across devices, and in prod.
// Priority: NEXT_PUBLIC_API_URL -> API_URL -> (browser) smart dev fallbacks -> (browser) window.origin -> ""
function computeApiBase(): string {
const envBase = process.env.NEXT_PUBLIC_API_URL || process.env.API_URL || "";
// If running in the browser, try to adapt localhost to current hostname for LAN/mobile testing
if (typeof window !== "undefined") {
try {
if (envBase) {
const u = new URL(envBase);
const isLocalHost = ["localhost", "127.0.0.1", "::1"].includes(u.hostname);
if (isLocalHost) {
// Replace localhost with the actual device hostname so other devices can reach the dev machine
const protocol = u.protocol || window.location.protocol;
const hostname = window.location.hostname; // e.g., 192.168.x.x or your.dev.domain
const port = u.port ? `:${u.port}` : "";
return `${protocol}//${hostname}${port}`;
}
return u.origin;
}
// No env base provided — provide a sensible dev fallback
// If Next dev server is on 3000, assume backend on the same host port 5000
if (window.location.port === "3000") {
const protocol = window.location.protocol;
const hostname = window.location.hostname;
return `${protocol}//${hostname}:5000`;
}
// Otherwise, assume same origin will proxy /api (works if reverse proxy is configured)
return window.location.origin;
} catch {
// Fallbacks below
}
}
// On the server (or if window not available), use envBase if present; otherwise empty string.
return envBase || "";
}
export const API_BASE = computeApiBase();
// Resolve a URL or path to use the API origin. If it's a relative path, prefix with API_BASE.
// If it's an absolute URL but points to localhost/127.0.0.1/::1, rewrite its origin to API_BASE.
export function resolveToApiOrigin(urlOrPath: string | null | undefined): string | null {
const raw = (urlOrPath || "").trim();
if (!raw) return null;
try {
if (raw.startsWith("http")) {
const u = new URL(raw);
const isLocal = ["localhost", "127.0.0.1", "::1"].includes(u.hostname);
if (isLocal && API_BASE) {
const api = new URL(API_BASE);
u.protocol = api.protocol;
u.hostname = api.hostname;
u.port = api.port;
return u.toString();
}
return raw; // already absolute and not localhost
}
} catch {
// fall through to relative handling
}
return API_BASE ? `${API_BASE}${raw}` : raw;
}
// The parsed JSON body of a failed request — v1 sends `message` (some routes add a
// machine-readable `code` or extra detail fields); for v2 it is the `error` object
// (`code`, `message`, and `fields` on validation errors).
export type ApiErrorData = { message?: string; code?: string; [key: string]: unknown };
export class ApiError extends Error {
constructor(public readonly status: number, message: string, public readonly data?: ApiErrorData) {
super(message);
this.name = "ApiError";
}
}
export async function apiFetch<T = unknown>(path: string, options: ApiOptions = {}): Promise<T> {
const { method = "GET", headers = {}, body, authToken, nextOptions } = options;
const url = path.startsWith("http") ? path : `${API_BASE}${path}`;
// On the server a relative URL has no origin to resolve against, and Next's
// patched fetch never settles on one during prerender (the build then times out
// every page). Fail fast instead so callers can degrade.
if (typeof window === "undefined" && !url.startsWith("http")) {
throw new Error(`API base URL is not configured (set NEXT_PUBLIC_API_URL or API_URL); cannot fetch ${path}`);
}
const mergedHeaders: Record<string, string> = { ...headers };
if (!(body instanceof FormData)) {
mergedHeaders["Content-Type"] = "application/json";
}
if (authToken) {
mergedHeaders["Authorization"] = `Bearer ${authToken}`;
}
const res = await fetch(url, {
method,
headers: mergedHeaders as HeadersInit,
body: body instanceof FormData ? body : body != null ? JSON.stringify(body) : undefined,
...nextOptions,
} as RequestInit);
if (!res.ok) {
const text = await res.text().catch(() => "");
let message = text || `Request failed with status ${res.status}`;
let data: ApiErrorData | undefined;
// Backend returns { message: "..." } — extract it so callers get a plain string
try {
const json = JSON.parse(text);
if (json?.message && typeof json.message === "string") message = json.message;
data = json;
// /api/v2 errors: { error: { code, message, fields?, reason? } }. `code` is the specific
// reason when there is one (TWO_FACTOR_REQUIRED, OTHER_CAMPUS…), like v1; v2Code is v2's own.
if (json?.error && typeof json.error === "object" && typeof json.error.message === "string") {
message = json.error.message;
data = { ...json.error, code: json.error.reason || json.error.code, v2Code: json.error.code };
}
} catch { /* not JSON — use raw text */ }
// An admin/supervisor session from before 2FA was required for their role:
// end it and send them to log in, where they enrol.
// The admin's "view as" session ended or expired: put their own session back.
if (res.status === 401 && data?.code === "IMPERSONATION_ENDED" && typeof window !== "undefined") {
const { restoreAdmin } = await import("@/lib/impersonation");
restoreAdmin();
}
if (res.status === 401 && data?.code === "TWO_FACTOR_REQUIRED" && typeof window !== "undefined") {
localStorage.removeItem("hope_events_token");
localStorage.removeItem("hope_events_user_cache");
if (!window.location.pathname.startsWith("/login")) {
const back = window.location.pathname + window.location.search;
window.location.href = `/login?reason=2fa&redirect=${encodeURIComponent(back)}`;
}
}
throw new ApiError(res.status, message, data);
}
const contentType = res.headers.get("content-type") || "";
if (contentType.includes("application/json")) {
return res.json();
}
// Non-JSON responses come back as text; callers that expect that pass T = string.
return (await res.text()) as T;
}
// For server components that prerender a public list: during `next build` the
// backend is often not running (or no API URL is set), so fall back to an empty
// list rather than failing the build — the page fills in on its first revalidate.
// At runtime the error still propagates, so ISR keeps serving the last good page
// instead of caching an empty one.
export async function apiFetchListForPrerender<T>(path: string, options: ApiOptions = {}): Promise<T[]> {
try {
return (await apiFetch<T[]>(path, options)) || [];
} catch (err) {
if (process.env.NEXT_PHASE === "phase-production-build") return [];
throw err;
}
}
// Several list endpoints (/api/users, /api/payments) are paginated and cap
// `limit` at 200 server-side, so a single request can silently miss records
// beyond the first page. This walks every page and returns the full list.
async function fetchAllPages<T>(path: string, token: string, params: Record<string, string> = {}): Promise<T[]> {
const query = new URLSearchParams({ ...params, limit: "200", page: "1" });
const first = await apiFetch<Paginated<T>>(`${path}?${query.toString()}`, { authToken: token });
const items: T[] = Array.isArray(first?.data) ? first.data : [];
const pages = first?.pages || 1;
if (pages > 1) {
// Page 1 told us the total page count — fetch the rest concurrently instead of
// awaiting them one at a time. This function is called on every dashboard poll
// (see useVisiblePolling usages), so a serial loop here directly slows those polls.
const remaining = await Promise.all(
Array.from({ length: pages - 1 }, (_, i) => {
const page = i + 2;
const pageQuery = new URLSearchParams({ ...params, limit: "200", page: String(page) });
return apiFetch<Paginated<T>>(`${path}?${pageQuery.toString()}`, { authToken: token });
})
);
for (const res of remaining) {
if (Array.isArray(res?.data)) items.push(...res.data);
}
}
return items;
}
export function fetchAllUsers(token: string, params: Record<string, string> = {}): Promise<User[]> {
return fetchAllPages<User>("/api/users", token, params);
}
export function fetchAllPayments(token: string, params: Record<string, string> = {}): Promise<Payment[]> {
return fetchAllPages<Payment>("/api/payments", token, params);
}
// Starts an online payment for everything still owed on one of my registrations (API v2), with
// an optional donation on top. Partial amounts are only taken from the supervisor payments page.
export type CheckoutResponse = { redirectUrl?: string; priceUpdated?: boolean; newTotal?: number; message?: string };
export async function createFullPaymentCheckout(token: string, registrationId: string, donationAmount?: number): Promise<CheckoutResponse> {
const { apiV2 } = await import("@/lib/apiV2");
const { data } = await apiV2("post", "/registrations/{id}/checkout", {
params: { id: registrationId },
authToken: token,
body: {
...(donationAmount && donationAmount > 0 ? { donationAmount } : {}),
successUrl: window.location.origin + "/payment/success",
cancelUrl: window.location.origin + "/payment/cancel",
failureUrl: window.location.origin + "/payment/failure",
},
});
// The price changed since registering: nothing was started — show the new amount owing.
if (data.priceUpdated) return { priceUpdated: true, newTotal: data.newBalance, message: data.message };
return { redirectUrl: data.redirectUrl };
}