api-organization

What this skill does

# API Organization Pattern

This skill defines the standardized API organization pattern used throughout this codebase. All external API integrations follow the same 5-file structure for consistency, type safety, and maintainability.

## When to Use This Skill

Use this skill when:
- Creating new API endpoints or integrations
- Adding new API categories or domains
- Implementing role-based API access (admin vs regular users)
- Modifying existing API structure
- Setting up authentication for API calls
- Creating type-safe API wrappers

## Core Principles

1. **Single Source of Truth** - All API URLs defined once in `endpoints.ts`
2. **Type Safety** - Full TypeScript coverage from params to responses
3. **Role-Based Access** - Separate clients for regular vs admin endpoints
4. **Centralized Auth** - Authentication handled automatically by clients
5. **DRY Code** - Reusable client functions, no duplicate endpoint definitions

## The 5-File System

All API code lives in `src/lib/api/` with exactly these files:

```
src/lib/api/
├── endpoint-types.ts       # TypeScript types for all endpoints
├── endpoints.ts            # URL definitions organized by domain
├── api-client.ts           # Generic authenticated API client
├── admin-api-client.ts     # Admin-only API client with role checks
└── protected-endpoints.ts  # Type-safe wrapper functions
```

### File Purposes

**1. endpoint-types.ts**
- Define all TypeScript interfaces for API data
- Organize types by domain (e.g., audiences, instances, membership)
- Include param types, response types, and request body DTOs
- Provide utility types for extracting types

See `references/endpoint-types-pattern.md` for detailed structure.

**2. endpoints.ts**
- Define all API endpoint URLs in one place
- Organize by feature/domain matching types
- Use functions that accept parameters and return URLs
- Support environment variable base URLs

See `references/endpoints-pattern.md` for detailed structure.

**3. api-client.ts**
- Generic API client with automatic authentication
- Error parsing and handling
- Support for GET, POST, PUT, DELETE methods
- Server-side only ('use server')

See `references/api-client-pattern.md` for implementation.

**4. admin-api-client.ts**
- Admin-specific API client
- Role validation (Admin/SuperAdmin groups)
- Permission checking functions
- Throws AdminAuthError if unauthorized

See `references/admin-api-client-pattern.md` for implementation.

**5. protected-endpoints.ts**
- Type-safe wrapper functions combining URLs + types + clients
- Organized to match endpoint-types structure
- Provides clean import: `import { api } from '@/lib/api/protected-endpoints'`
- No 'use server' directive (exports objects)

See `references/protected-endpoints-pattern.md` for detailed structure.

## Authentication System

This application uses **Supabase Auth** for authentication. All API requests require authentication via Supabase access tokens.

### Supabase Client Structure
```
src/lib/supabase/
├── client.ts      # Browser-side Supabase client
├── server.ts      # Server-side Supabase client (RSC, Server Actions)
└── middleware.ts  # Middleware helper for auth cookie refresh
```

### Auth Flow
1. User authenticates via Supabase (email/password, OAuth, etc.)
2. Supabase stores session in httpOnly cookies
3. Middleware refreshes session on every request
4. Server components/actions use `createClient()` from `server.ts`
5. API client extracts access token from session automatically

See `references/supabase-auth-integration.md` for detailed implementation.

## Role-Based Access Pattern

### Regular User Endpoints
Use `api-client.ts` functions with automatic Supabase auth:
```typescript
import { apiGet, apiPost } from '@/lib/api/api-client';

// Access token extracted from Supabase session automatically
const data = await apiGet<ResponseType>(url);
```

### Admin-Only Endpoints
Use `admin-api-client.ts` functions with role validation:
```typescript
import { adminApiRequest, checkAdminPermission } from '@/lib/api/admin-api-client';

// Validate admin access first (checks user role from database)
await checkAdminPermission(); // Throws if not admin

// Make admin API request
const data = await adminApiRequest<ResponseType>(url, options);
```

### Admin Roles
Admin roles are stored in the `users` table:
- `users.role` = `'admin'` - Standard admin access
- `users.role` = `'member'` - Regular user access

First user in a family is automatically assigned admin role.

## Adding New API Endpoints

Follow this exact order when integrating a new API into the application:

### Step 1: Define Types in endpoint-types.ts

```typescript
// 1. Define response type(s)
export interface ResourceItem {
  id: string;
  name: string;
  // ... other fields from your API response
}

// 2. Define request DTO(s) for mutations
export interface CreateResourceDto {
  name: string;
  // ... fields required to create
}

// 3. Add parameter types to EndpointParams interface
export interface EndpointParams {
  // ... existing domains

  resources: {
    list: void;              // No params needed
    get: { id: string };     // Requires ID
    create: void;            // Body in request, not params
    update: { id: string };
    delete: { id: string };
  };
}

// 4. Add response types to EndpointResponses interface
export interface EndpointResponses {
  // ... existing domains

  resources: {
    list: ResourceItem[];
    get: ResourceItem;
    create: ResourceItem;
    update: ResourceItem;
    delete: void;
  };
}

// 5. Add request body types to EndpointBodies interface (if needed)
export interface EndpointBodies {
  // ... existing domains

  resources: {
    create: CreateResourceDto;
    update: CreateResourceDto;
  };
}
```

### Step 2: Define URLs in endpoints.ts

```typescript
export const API_ENDPOINTS = {
  // ... existing categories

  resources: {
    list: () => `${API_BASE}/api/resources`,
    get: (id: string) => `${API_BASE}/api/resources/${id}`,
    create: () => `${API_BASE}/api/resources`,
    update: (id: string) => `${API_BASE}/api/resources/${id}`,
    delete: (id: string) => `${API_BASE}/api/resources/${id}`,
  },
};
```

### Step 3: Add Wrapper in protected-endpoints.ts

```typescript
export const api = {
  // ... existing domains

  resources: {
    async list(): Promise<ResourceItem[]> {
      return apiGet<ResourceItem[]>(
        API_ENDPOINTS.resources.list()
      );
    },

    async get(id: string): Promise<ResourceItem> {
      return apiGet<ResourceItem>(
        API_ENDPOINTS.resources.get(id)
      );
    },

    async create(data: CreateResourceDto): Promise<ResourceItem> {
      return apiPost<ResourceItem, CreateResourceDto>(
        API_ENDPOINTS.resources.create(),
        data
      );
    },

    async update(id: string, data: CreateResourceDto): Promise<ResourceItem> {
      return apiPut<ResourceItem, CreateResourceDto>(
        API_ENDPOINTS.resources.update(id),
        data
      );
    },

    async delete(id: string): Promise<void> {
      return apiDelete<void>(
        API_ENDPOINTS.resources.delete(id)
      );
    },
  },
};
```

### Step 4: Use in Application Code

```typescript
'use server';

import { api } from '@/lib/api/protected-endpoints';

// In a server component or server action
const resources = await api.resources.list();
const resource = await api.resources.get(id);
const newResource = await api.resources.create({
  name: 'New Resource'
});
```

## Naming Conventions

### Endpoint Operations
- `list` / `listAll` - GET multiple items
- `get` - GET single item
- `create` - POST new item
- `update` - PUT/PATCH existing item
- `delete` - DELETE item

### Type Naming
- Response types: PascalCase describing entity (e.g., `AudienceListItem`)
- DTOs: PascalCase with suffix (e.g., `CreateUserDto`, `UpdateSettingsDto`)
- Interfaces match plural for collections, singular for items

## Error Handling

All API clients handle errors automatically:

```typescript
try {
  const data = a