golid / rules

---
description: Patterns for frontend lib files — API client, auth, constants, utilities
globs: frontend/src/lib/*.ts
alwaysApply: false
---

# Frontend Lib Patterns

> **Thesis:** Lib files are the shared foundation: typed API client, auth store, constants, and utilities. Every API call is typed, every protected route is registered.

Follow the established patterns in `api.ts`, `auth.ts`, and `constants.ts`.

## API Client (`api.ts`)

### Adding a New API Module

Group types and methods together. Follow the established API object pattern:

```typescript
// 1. Define TypeScript interfaces matching backend response structs
export interface Item {
  id: string;
  title: string;
  // ... fields match the Go Detail struct exactly
}

export interface ItemListResult {
  items: Item[];
  total: number;
  page: number;
  per_page: number;
  total_pages: number;
}

// 2. Query builder for list endpoints (if filterable)
function buildItemQuery(params?: ItemListParams): string { ... }

// 3. API object with typed methods
export const itemsApi = {
  create: (data: CreateItemInput) => post<Item>("/items", data),
  list: (params?: ItemListParams) => get<ItemListResult>(`/items${buildItemQuery(params)}`),
  getById: (id: string) => get<Item>(`/items/${id}`),
  update: (id: string, data: Partial<Item>) => put<Item>(`/items/${id}`, data),
  delete: (id: string) => del<{ message: string }>(`/items/${id}`),
};
```

### Conventions

- **Use the convenience helpers** — `get`, `post`, `put`, `patch`, `del` from the same file. Never raw `fetch`.
- **Type every response** — `get<MyType>(...)` not `get<any>(...)`.
- **All endpoints start with `/`** — the `api()` function prepends `/api/v1`.
- **`skipAuth: true`** only for public endpoints (login, register, universities).
- **Optional fields use `?`** — match the Go struct's `omitempty` tags.

### Search/Filter Query Builder

For list endpoints with search and pagination, use a query builder function:

```typescript
function buildItemQuery(params?: { page?: number; perPage?: number; search?: string }): string {
  const p = new URLSearchParams();
  if (params?.page) p.set("page", String(params.page));
  if (params?.perPage) p.set("per_page", String(params.perPage));
  if (params?.search) p.set("search", params.search);
  const qs = p.toString();
  return qs ? `?${qs}` : "";
}
```

The scaffold tool generates this pattern automatically with `?search=` and `?page=` params for new modules.

### Error Handling

Errors thrown by `api()` are typed as `ApiError` with `message`, `code`, `status`, and optional `details`. Catch them with:

```typescript
try {
  await itemsApi.create(data);
} catch (err) {
  const apiErr = err as { message?: string; details?: Record<string, string> };
  if (apiErr.details) { /* field-level errors */ }
  else { toast.error(apiErr.message || "Something went wrong"); }
}
```

## Constants (`constants.ts`)

- **`PRIVATE_ROUTES`** — add every new protected route path. SSR middleware uses this for auth redirects. Missing entries = unauthenticated users see API errors instead of login redirect.

## Auth (`auth.ts`)

- Token refresh is handled automatically by `api()` on 401 responses.
- `auth.user` is the reactive user object — read in components, updated via `auth.updateUser()`.
- Don't access `localStorage` directly — use the `tokens` helper from `api.ts`.

## API Proxy (`frontend/src/routes/api/[...path].ts`)

- In production, all `/api/*` requests are proxied through SolidStart to the internal backend Cloud Run service.
- In dev, Vite proxy handles this (configured in `app.config.ts`), so the proxy route is not used.
- This file rarely changes. If you modify it, ensure: hop-by-hop headers are stripped, error responses return valid JSON with `code` field, and `BACKEND_URL` env var is respected.