Frontend Integration Guide¶

const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000/api/v1';

// Simple GET request
const response = await fetch(`${API_BASE_URL}/app/users/me`, {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
  },
});
const user = await response.json();

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);

// Get access token for API calls
async function getAccessToken(): Promise<string | null> {
  const { data: { session } } = await supabase.auth.getSession();
  return session?.access_token ?? null;
}

// Make authenticated request
async function fetchAPI<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
  const token = await getAccessToken();

  const response = await fetch(`${API_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...(token && { 'Authorization': `Bearer ${token}` }),
      ...options.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new APIError(error);
  }

  return response.json();
}

import { useAuth } from '@clerk/nextjs';

function MyComponent() {
  const { getToken } = useAuth();

  async function fetchData() {
    const token = await getToken();

    const response = await fetch(`${API_BASE_URL}/app/users/me`, {
      headers: {
        'Authorization': `Bearer ${token}`,
      },
    });

    return response.json();
  }
}

// The auth provider (Supabase/Clerk) handles token refresh automatically
// Just always call getSession()/getToken() before each request

async function makeRequest(endpoint: string) {
  // This always returns a fresh/valid token
  const { data: { session } } = await supabase.auth.getSession();

  if (!session) {
    // Redirect to login
    throw new Error('Not authenticated');
  }

  return fetch(`${API_BASE_URL}${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${session.access_token}`,
    },
  });
}

// ============================================
// Common Types
// ============================================

interface PaginatedResponse<T> {
  items: T[];
  total: number;
  skip: number;
  limit: number;
}

interface ErrorResponse {
  error: {
    code: string;
    message: string;
    details: Record<string, unknown>;
  };
}

// Pagination helper
interface PaginationInfo {
  total: number;
  skip: number;
  limit: number;
  currentPage: number;
  totalPages: number;
  hasNext: boolean;
  hasPrev: boolean;
}

function getPaginationInfo(response: PaginatedResponse<unknown>): PaginationInfo {
  const totalPages = Math.ceil(response.total / response.limit);
  const currentPage = Math.floor(response.skip / response.limit) + 1;

  return {
    total: response.total,
    skip: response.skip,
    limit: response.limit,
    currentPage,
    totalPages,
    hasNext: response.skip + response.items.length < response.total,
    hasPrev: response.skip > 0,
  };
}

// ============================================
// User Types
// ============================================

interface User {
  id: string;
  email: string;
  full_name: string | null;
  avatar_url: string | null;
  role: 'user' | 'admin' | 'superadmin';
  is_active: boolean;
  subscription_plan: 'free' | 'pro' | 'enterprise' | null;
  subscription_status: 'active' | 'canceled' | 'past_due' | 'trialing' | 'incomplete' | null;
  created_at: string; // ISO 8601
}

interface UserUpdate {
  full_name?: string;
  avatar_url?: string;
}

// ============================================
// Project Types
// ============================================

interface Project {
  id: string;
  name: string;
  description: string | null;
  owner_id: string;
  created_at: string;
  updated_at: string;
}

interface ProjectCreate {
  name: string;
  description?: string;
}

interface ProjectUpdate {
  name?: string;
  description?: string;
}

type ProjectListResponse = PaginatedResponse<Project>;

// ============================================
// File Types
// ============================================

interface FileUploadRequest {
  filename: string;
  content_type: string;
  size: number;
}

interface PresignedUploadResponse {
  upload_url: string;
  file_id: string;
  key: string;
  expires_in: number;
}

interface FileRecord {
  id: string;
  filename: string;
  content_type: string;
  size: number;
  status: 'pending' | 'uploaded' | 'failed';
  created_at: string;
}

interface DownloadUrlResponse {
  download_url: string;
  expires_in: number;
}

// ============================================
// AI Types
// ============================================

type MessageRole = 'system' | 'user' | 'assistant';

interface ChatMessage {
  role: MessageRole;
  content: string;
}

interface CompletionRequest {
  messages: ChatMessage[];
  model?: string;
  temperature?: number;
  max_tokens?: number;
  stream?: boolean;
}

interface SimpleCompletionRequest {
  prompt: string;
  system?: string;
  model?: string;
  temperature?: number;
  max_tokens?: number;
  stream?: boolean;
}

interface RoutedCompletionRequest {
  prompt: string;
  system?: string;
  complexity: 'simple' | 'moderate' | 'complex' | 'search';
  temperature?: number;
  max_tokens?: number;
}

interface TokenUsage {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
}

interface CompletionResponse {
  content: string;
  model: string;
  provider: string;
  usage: TokenUsage;
  finish_reason: string;
  latency_ms: number;
}

interface AIStatusResponse {
  available: boolean;
  providers: string[];
  default_provider: string;
  default_model: string;
}

// ============================================
// Billing Types
// ============================================

interface BillingStatus {
  plan: string;
  status: string | null;
  current_period_end: string | null;
  cancel_at_period_end: boolean;
  has_active_subscription: boolean;
}

interface CheckoutRequest {
  plan: 'monthly' | 'yearly';
  success_url: string;
  cancel_url: string;
}

interface CheckoutResponse {
  session_id: string;
  url: string;
}

interface PortalResponse {
  url: string;
}

interface Invoice {
  id: string;
  number: string | null;
  status: string;
  amount_due: number;
  amount_paid: number;
  currency: string;
  created: number;
  hosted_invoice_url: string | null;
  invoice_pdf: string | null;
}

// ============================================
// Usage Types
// ============================================

type UsageMetric =
  | 'api_requests'
  | 'ai_tokens'
  | 'ai_requests'
  | 'storage_bytes'
  | 'file_uploads'
  | 'file_downloads'
  | 'websocket_messages'
  | 'background_jobs'
  | 'email_sent';

interface UsageMetricInfo {
  current_period: number;
  previous_period: number;
  growth_rate: number;
  daily_average: number;
}

interface UsageSummaryResponse {
  metrics: Record<UsageMetric, UsageMetricInfo>;
  period: {
    start: string;
    end: string;
  };
}

interface UsageCurrentPeriodResponse {
  api_requests: number;
  ai_tokens: number;
  ai_requests: number;
  storage_bytes: number;
  file_uploads: number;
  file_downloads: number;
  websocket_messages: number;
  background_jobs: number;
  email_sent: number;
  period: {
    start: string;
    end: string;
  };
}

interface UsageTrendResponse {
  metric: UsageMetric;
  current_period: number;
  previous_period: number;
  growth_rate: number;
  daily_average: number;
  peak_day: string;
  peak_value: number;
  trend: 'increasing' | 'decreasing' | 'stable';
}

interface UsageDailyDataPoint {
  date: string;
  value: number;
}

interface UsageDailyResponse {
  metric: UsageMetric;
  data: UsageDailyDataPoint[];
  total: number;
  average: number;
}

interface UsageBreakdownResponse {
  metric: UsageMetric;
  breakdown: Record<string, number>;
  total: number;
}

interface UsageMetricDefinition {
  key: UsageMetric;
  name: string;
  description: string;
  unit: string;
}

interface UsageMetricsListResponse {
  metrics: UsageMetricDefinition[];
}

// ============================================
// Health Types
// ============================================

interface HealthResponse {
  status: string;
  timestamp: string;
}

interface HealthReadyResponse {
  status: string;
  timestamp: string;
  components: {
    database: { status: string };
    cache: { status: string };
  };
}

// API Error codes
type ErrorCode =
  | 'BAD_REQUEST'
  | 'AUTHENTICATION_ERROR'
  | 'AUTHORIZATION_ERROR'
  | 'NOT_FOUND'
  | 'CONFLICT'
  | 'VALIDATION_ERROR'
  | 'RATE_LIMIT_EXCEEDED'
  | 'EXTERNAL_SERVICE_ERROR'
  | 'SERVICE_UNAVAILABLE';

class APIError extends Error {
  code: ErrorCode;
  details: Record<string, unknown>;
  status: number;

  constructor(response: ErrorResponse, status: number = 400) {
    super(response.error.message);
    this.code = response.error.code as ErrorCode;
    this.details = response.error.details;
    this.status = status;
    this.name = 'APIError';
  }

  // Helper methods
  isNotFound(): boolean {
    return this.code === 'NOT_FOUND';
  }

  isAuthError(): boolean {
    return this.code === 'AUTHENTICATION_ERROR' || this.code === 'AUTHORIZATION_ERROR';
  }

  isRateLimited(): boolean {
    return this.code === 'RATE_LIMIT_EXCEEDED';
  }

  isValidationError(): boolean {
    return this.code === 'VALIDATION_ERROR';
  }
}

// lib/api.ts

const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL!;

interface RequestOptions extends RequestInit {
  params?: Record<string, string | number>;
}

async function getAuthToken(): Promise<string | null> {
  // Implement based on your auth provider
  const { data: { session } } = await supabase.auth.getSession();
  return session?.access_token ?? null;
}

export async function api<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const { params, ...fetchOptions } = options;

  // Build URL with query params
  let url = `${API_BASE_URL}${endpoint}`;
  if (params) {
    const searchParams = new URLSearchParams();
    Object.entries(params).forEach(([key, value]) => {
      searchParams.append(key, String(value));
    });
    url += `?${searchParams.toString()}`;
  }

  // Get auth token
  const token = await getAuthToken();

  // Make request
  const response = await fetch(url, {
    ...fetchOptions,
    headers: {
      'Content-Type': 'application/json',
      ...(token && { 'Authorization': `Bearer ${token}` }),
      ...fetchOptions.headers,
    },
  });

  // Handle errors
  if (!response.ok) {
    const errorData = await response.json();
    throw new APIError(errorData, response.status);
  }

  // Handle 204 No Content
  if (response.status === 204) {
    return undefined as T;
  }

  return response.json();
}

// Convenience methods
export const apiClient = {
  get: <T>(endpoint: string, params?: Record<string, string | number>) =>
    api<T>(endpoint, { method: 'GET', params }),

  post: <T>(endpoint: string, data?: unknown) =>
    api<T>(endpoint, { method: 'POST', body: JSON.stringify(data) }),

  patch: <T>(endpoint: string, data?: unknown) =>
    api<T>(endpoint, { method: 'PATCH', body: JSON.stringify(data) }),

  delete: <T>(endpoint: string) =>
    api<T>(endpoint, { method: 'DELETE' }),
};

// lib/axios.ts

import axios, { AxiosError } from 'axios';

const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  headers: {
    'Content-Type': 'application/json',
  },
});

// Request interceptor - add auth token
apiClient.interceptors.request.use(async (config) => {
  const { data: { session } } = await supabase.auth.getSession();

  if (session?.access_token) {
    config.headers.Authorization = `Bearer ${session.access_token}`;
  }

  return config;
});

// Response interceptor - handle errors
apiClient.interceptors.response.use(
  (response) => response,
  (error: AxiosError<ErrorResponse>) => {
    if (error.response) {
      throw new APIError(error.response.data, error.response.status);
    }
    throw error;
  }
);

export { apiClient };

// lib/query.ts

import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      retry: (failureCount, error) => {
        // Don't retry on auth errors
        if (error instanceof APIError && error.isAuthError()) {
          return false;
        }
        return failureCount < 3;
      },
    },
  },
});

// Query keys factory
export const queryKeys = {
  user: {
    current: ['user', 'current'] as const,
  },
  projects: {
    all: ['projects'] as const,
    list: (params: { skip?: number; limit?: number; search?: string }) =>
      ['projects', 'list', params] as const,
    detail: (id: string) => ['projects', 'detail', id] as const,
  },
  billing: {
    status: ['billing', 'status'] as const,
    invoices: ['billing', 'invoices'] as const,
  },
  ai: {
    status: ['ai', 'status'] as const,
  },
  usage: {
    summary: ['usage', 'summary'] as const,
    currentPeriod: ['usage', 'current-period'] as const,
    trends: (metric: string) => ['usage', 'trends', metric] as const,
    daily: (metric: string, days: number) => ['usage', 'daily', metric, days] as const,
    breakdown: (metric: string) => ['usage', 'breakdown', metric] as const,
    metrics: ['usage', 'metrics'] as const,
  },
};

// hooks/usePaginatedProjects.ts

import { useQuery } from '@tanstack/react-query';
import { useState } from 'react';

interface UsePaginatedProjectsOptions {
  initialLimit?: number;
  search?: string;
}

export function usePaginatedProjects(options: UsePaginatedProjectsOptions = {}) {
  const { initialLimit = 20, search } = options;
  const [page, setPage] = useState(0);

  const query = useQuery({
    queryKey: queryKeys.projects.list({
      skip: page * initialLimit,
      limit: initialLimit,
      search,
    }),
    queryFn: () =>
      apiClient.get<ProjectListResponse>('/app/projects', {
        skip: page * initialLimit,
        limit: initialLimit,
        ...(search && { search }),
      }),
  });

  const pagination = query.data ? getPaginationInfo(query.data) : null;

  return {
    ...query,
    pagination,
    page,
    setPage,
    nextPage: () => setPage((p) => p + 1),
    prevPage: () => setPage((p) => Math.max(0, p - 1)),
  };
}

// hooks/useUpdateProject.ts

import { useMutation, useQueryClient } from '@tanstack/react-query';

export function useUpdateProject(projectId: string) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (data: ProjectUpdate) =>
      apiClient.patch<Project>(`/app/projects/${projectId}`, data),

    // Optimistic update
    onMutate: async (newData) => {
      // Cancel outgoing refetches
      await queryClient.cancelQueries({
        queryKey: queryKeys.projects.detail(projectId),
      });

      // Snapshot previous value
      const previousProject = queryClient.getQueryData<Project>(
        queryKeys.projects.detail(projectId)
      );

      // Optimistically update
      if (previousProject) {
        queryClient.setQueryData(
          queryKeys.projects.detail(projectId),
          { ...previousProject, ...newData }
        );
      }

      return { previousProject };
    },

    // Rollback on error
    onError: (err, newData, context) => {
      if (context?.previousProject) {
        queryClient.setQueryData(
          queryKeys.projects.detail(projectId),
          context.previousProject
        );
      }
    },

    // Refetch after success or error
    onSettled: () => {
      queryClient.invalidateQueries({
        queryKey: queryKeys.projects.detail(projectId),
      });
    },
  });
}

// hooks/useFileUpload.ts

interface UseFileUploadOptions {
  onProgress?: (progress: number) => void;
  onSuccess?: (file: FileRecord) => void;
  onError?: (error: Error) => void;
}

export function useFileUpload(options: UseFileUploadOptions = {}) {
  const [isUploading, setIsUploading] = useState(false);
  const [progress, setProgress] = useState(0);

  const upload = async (file: File) => {
    setIsUploading(true);
    setProgress(0);

    try {
      // 1. Get presigned upload URL
      const presigned = await apiClient.post<PresignedUploadResponse>(
        '/app/files/upload-url',
        {
          filename: file.name,
          content_type: file.type,
          size: file.size,
        }
      );

      // 2. Upload to storage (with progress tracking)
      await new Promise<void>((resolve, reject) => {
        const xhr = new XMLHttpRequest();

        xhr.upload.addEventListener('progress', (e) => {
          if (e.lengthComputable) {
            const pct = Math.round((e.loaded / e.total) * 100);
            setProgress(pct);
            options.onProgress?.(pct);
          }
        });

        xhr.addEventListener('load', () => {
          if (xhr.status >= 200 && xhr.status < 300) {
            resolve();
          } else {
            reject(new Error('Upload failed'));
          }
        });

        xhr.addEventListener('error', () => reject(new Error('Upload failed')));

        xhr.open('PUT', presigned.upload_url);
        xhr.setRequestHeader('Content-Type', file.type);
        xhr.send(file);
      });

      // 3. Confirm upload
      const fileRecord = await apiClient.post<FileRecord>(
        '/app/files/confirm',
        { file_id: presigned.file_id }
      );

      options.onSuccess?.(fileRecord);
      return fileRecord;

    } catch (error) {
      options.onError?.(error as Error);
      throw error;
    } finally {
      setIsUploading(false);
    }
  };

  return {
    upload,
    isUploading,
    progress,
  };
}

// components/ErrorBoundary.tsx

import { useEffect } from 'react';
import { useRouter } from 'next/navigation';

export function useAPIErrorHandler() {
  const router = useRouter();

  const handleError = (error: unknown) => {
    if (error instanceof APIError) {
      switch (error.code) {
        case 'AUTHENTICATION_ERROR':
          // Redirect to login
          router.push('/login');
          break;

        case 'AUTHORIZATION_ERROR':
          // Show forbidden page
          router.push('/403');
          break;

        case 'NOT_FOUND':
          // Show 404
          router.push('/404');
          break;

        case 'RATE_LIMIT_EXCEEDED':
          // Show rate limit message
          const retryAfter = error.details.retry_after as number;
          toast.error(`Too many requests. Try again in ${retryAfter} seconds.`);
          break;

        case 'VALIDATION_ERROR':
          // Show field-specific error
          const field = error.details.field as string;
          toast.error(`${field}: ${error.message}`);
          break;

        default:
          toast.error(error.message);
      }
    } else {
      toast.error('An unexpected error occurred');
      console.error(error);
    }
  };

  return handleError;
}

// hooks/useFormWithAPI.ts

interface UseFormWithAPIOptions<T> {
  onSubmit: (data: T) => Promise<void>;
}

export function useFormWithAPI<T extends Record<string, unknown>>(
  options: UseFormWithAPIOptions<T>
) {
  const [errors, setErrors] = useState<Record<string, string>>({});
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleSubmit = async (data: T) => {
    setErrors({});
    setIsSubmitting(true);

    try {
      await options.onSubmit(data);
    } catch (error) {
      if (error instanceof APIError && error.isValidationError()) {
        const field = error.details.field as string;
        if (field) {
          setErrors({ [field]: error.message });
        }
      } else {
        throw error;
      }
    } finally {
      setIsSubmitting(false);
    }
  };

  return {
    errors,
    isSubmitting,
    handleSubmit,
    clearErrors: () => setErrors({}),
  };
}

// hooks/useStreamingCompletion.ts

interface UseStreamingCompletionOptions {
  onChunk?: (chunk: string) => void;
  onComplete?: (fullText: string) => void;
  onError?: (error: Error) => void;
}

export function useStreamingCompletion(options: UseStreamingCompletionOptions = {}) {
  const [isStreaming, setIsStreaming] = useState(false);
  const [content, setContent] = useState('');

  const stream = async (request: SimpleCompletionRequest) => {
    setIsStreaming(true);
    setContent('');

    try {
      const token = await getAuthToken();

      const response = await fetch(`${API_BASE_URL}/app/ai/chat`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${token}`,
        },
        body: JSON.stringify({ ...request, stream: true }),
      });

      if (!response.ok) {
        throw new Error('Stream request failed');
      }

      const reader = response.body?.getReader();
      const decoder = new TextDecoder();

      let fullContent = '';

      while (reader) {
        const { done, value } = await reader.read();

        if (done) break;

        const chunk = decoder.decode(value, { stream: true });
        const lines = chunk.split('\n');

        for (const line of lines) {
          if (line.startsWith('data: ')) {
            const data = line.slice(6);

            if (data === '[DONE]') {
              break;
            }

            fullContent += data;
            setContent(fullContent);
            options.onChunk?.(data);
          }
        }
      }

      options.onComplete?.(fullContent);
      return fullContent;

    } catch (error) {
      options.onError?.(error as Error);
      throw error;
    } finally {
      setIsStreaming(false);
    }
  };

  return {
    stream,
    isStreaming,
    content,
    reset: () => setContent(''),
  };
}

// lib/supabase/client.ts
import { createBrowserClient } from '@supabase/ssr';

export function createClient() {
  return createBrowserClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
  );
}

// lib/supabase/server.ts
import { createServerClient, type CookieOptions } from '@supabase/ssr';
import { cookies } from 'next/headers';

export async function createClient() {
  const cookieStore = await cookies();

  return createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll();
        },
        setAll(cookiesToSet) {
          try {
            cookiesToSet.forEach(({ name, value, options }) =>
              cookieStore.set(name, value, options)
            );
          } catch {
            // Called from Server Component
          }
        },
      },
    }
  );
}