Backend Integration

┌─────────────────┐
│  Next.js Chat   │
│   (Frontend)    │
└────────┬────────┘
         │
         │ Bearer Token
         │
         ▼
┌─────────────────┐
│ BackendAPIService│
│  (HTTP Client)   │
└────────┬────────┘
         │
         │ REST API
         │
         ▼
┌─────────────────┐
│  Laravel API    │
│   (Backend)     │
└─────────────────┘

NEXT_PUBLIC_BACKEND_API_URL=https://api.your-domain.com

const service = createBackendAPIService({
  token: 'your-user-session-token'
});

throw new BackendAuthError();
// Message: "No se pudo autenticar con el backend. Verifica tu sesión."

// Backend response
{
  "data": [...items],
  "meta": { "current_page": 1, "total": 50 },
  "links": { "next": "..." }
}

// Unwrapped result
{
  items: [...],
  pagination: {
    page: 1,
    lastPage: 5,
    perPage: 10,
    total: 50,
    hasMore: true
  }
}

const DEFAULT_TIMEOUT_MS = 8000; // 8 seconds

throw new BackendTimeoutError(endpoint, timeoutMs);
// Message: "El servidor tardó más de 8s en responder. 
//           Intenta con filtros más específicos."

const result = await service.getActivos({
  tipo?: 'mobiliario' | 'equipo',
  estado?: string,
  busqueda?: string,
  page?: number
});

const result = await service.getMantenimientos({
  estado?: 'pendiente' | 'en_progreso' | 'completado',
  prioridad?: 'baja' | 'media' | 'alta',
  activo_id?: number,
  page?: number
});

const result = await service.getCalendario({
  fecha_desde?: string,  // ISO date
  fecha_hasta?: string,  // ISO date
  page?: number
});

const result = await service.getReportes({
  tipo?: string,
  fecha_desde?: string,
  fecha_hasta?: string,
  page?: number
});

const result = await service.getRepuestos({
  bajo_stock?: boolean,
  categoria?: string,
  busqueda?: string,
  page?: number
});

const result = await service.getProveedores();

try {
  await service.getActivos();
} catch (error) {
  if (error instanceof BackendAPIError) {
    console.log(error.message);    // Error description
    console.log(error.statusCode); // HTTP status code
    console.log(error.endpoint);   // Failed endpoint
  }
}

if (error instanceof BackendTimeoutError) {
  // statusCode: 408
  // Suggests using more specific filters
}

if (error instanceof BackendAuthError) {
  // statusCode: 401
  // Suggests verifying session
}

try {
  const result = await service.getActivos();
} catch (error) {
  if (error instanceof BackendAuthError) {
    // Redirect to login
  } else if (error instanceof BackendTimeoutError) {
    // Suggest more specific filters
  } else if (error instanceof BackendAPIError) {
    // Show generic error message
  } else {
    // Network or unknown error
  }
}

import { createBackendAPIService } from '@/app/lib/services/backend-api-service';
import { cookies } from 'next/headers';

// Inside a Server Action or API Route
export async function fetchAssetsAction() {
  // Extract token from cookies (Laravel Sanctum)
  const cookieStore = await cookies();
  const token = cookieStore.get('session_token')?.value;
  
  if (!token) {
    throw new Error('Not authenticated');
  }
  
  // Create service instance with token
  const service = createBackendAPIService({ token });
  
  // Query backend
  const assets = await service.getActivos({
    estado: 'activo',
    page: 1
  });
  
  return assets;
}

const service = createBackendAPIService({
  token: userToken,
  timeoutMs: 10000,      // 10 second timeout
  maxRetries: 3,         // 4 total attempts
  backoffBaseMs: 2000    // 2 second base backoff
});

import { BackendAPIService } from '@/app/lib/services/backend-api-service';

const mockFetch = vi.fn();

const service = new BackendAPIService(
  { baseUrl: 'http://test.com', token: 'test' },
  { fetchFn: mockFetch }
);

service.getActivos({
  tipo: 'equipo',      // ✓ Included
  estado: undefined,   // ✗ Excluded
  busqueda: ''        // ✗ Excluded
});

// Result: /api/catalogo/activos?tipo=equipo

import { vi } from 'vitest';
import type { BackendAPIService } from '@/app/lib/services/backend-api-service';

// Mock the service
const mockService: Partial<BackendAPIService> = {
  getActivos: vi.fn().mockResolvedValue({
    items: [{ id: 1, nombre: 'Test Asset' }],
    pagination: { page: 1, total: 1, hasMore: false }
  })
};

import { BackendTimeoutError } from '@/app/lib/services/backend-api-service';

test('handles timeout gracefully', async () => {
  const mockService = {
    getActivos: vi.fn().mockRejectedValue(
      new BackendTimeoutError('/api/catalogo/activos', 8000)
    )
  };
  
  await expect(mockService.getActivos()).rejects.toThrow(BackendTimeoutError);
});