HTTP

CorsAdapter

Adapter per configurazione CORS cross-origin. Fornisce CorsConfig, ICorsAdapter, CorsAdapter e CorsAdapterFactory con preset per sviluppo.

Quando usarlo

CorsAdapter applica una policy CORS esplicita a un'istanza Axios e fornisce messaggi diagnostici quando le richieste cross-origin falliscono. Usalo quando:

l'applicazione chiama API ospitate su origin diversi;
vuoi un client Axios con withCredentials e Content-Type coerenti applicati via interceptor;
ti serve un messaggio d'errore più chiaro di "Network Error" generico in caso di problemi CORS.

CorsAdapter lavora su AxiosInstance. Per FetchHttpClient usa direttamente withCredentials: true nella baseConfig: la Fetch API gestisce nativamente CORS senza adapter aggiuntivi.

`CorsConfig`

interface CorsConfig {
  allowedOrigins: string[] | '*'
  allowedMethods: string[]
  allowedHeaders: string[]
  allowCredentials: boolean
  maxAge?: number
  exposedHeaders?: string[]
}

Campo	Tipo	Descrizione
`allowedOrigins`	`string[] \| '*'`	Domini consentiti per le richieste cross-origin. `'*'` consente tutti i domini.
`allowedMethods`	`string[]`	Metodi HTTP consentiti (es. `['GET', 'POST', 'PUT', 'DELETE']`). Non può essere vuoto.
`allowedHeaders`	`string[]`	Headers consentiti nelle richieste (es. `['Content-Type', 'Authorization']`). Non può essere vuoto.
`allowCredentials`	`boolean`	Se `true`, applica `withCredentials: true` su ogni richiesta.
`maxAge`	`number`	Durata cache del preflight in secondi (opzionale).
`exposedHeaders`	`string[]`	Headers che il client può leggere dalla risposta (opzionale).

`ICorsAdapter`

interface ICorsAdapter {
  applyToConfig(config: AxiosRequestConfig): AxiosRequestConfig
  handleCorsError(error: AxiosError): never
  createCorsEnabledClient(baseConfig?: AxiosRequestConfig): AxiosInstance
}

Metodo	Signature	Descrizione
`applyToConfig`	`(config: AxiosRequestConfig) => AxiosRequestConfig`	Applica `withCredentials` e `Content-Type` default su una singola config.
`handleCorsError`	`(error: AxiosError) => never`	Lancia errore con messaggio diagnostico CORS.
`createCorsEnabledClient`	`(baseConfig?: AxiosRequestConfig) => AxiosInstance`	Crea un'istanza Axios con interceptors request/response che applicano la policy.

`CorsAdapter`

Implementazione concreta. Valida la CorsConfig nel costruttore.

class CorsAdapter implements ICorsAdapter {
  constructor(corsConfig: CorsConfig)
}

Parametro	Tipo	Default	Descrizione
`corsConfig`	`CorsConfig`	—	Configurazione CORS. Lancia `Error` se `allowedMethods` o `allowedHeaders` sono vuoti.

Comportamento

applyToConfig: se Content-Type è in allowedHeaders, viene preservato l'esistente o impostato a application/json. withCredentials viene impostato se allowCredentials è true o se la config originale lo richiedeva.
handleCorsError: se l'errore ha una response HTTP, lo rilancia invariato. Se ha solo request (network error), lancia un errore con messaggio:
Possibile errore CORS: <message>. Verifica che il server includa l'header 'Access-Control-Allow-Origin' e supporti il metodo <METHOD>.
createCorsEnabledClient: crea axios.create(baseConfig) e registra interceptors che applicano applyToConfig su ogni request e handleCorsError su ogni response error.

`CorsAdapterFactory`

Factory per creare adapter con configurazioni predefinite.

Metodo	Signature	Descrizione
`createDefaultAdapter`	`() => ICorsAdapter`	Adapter permissivo per sviluppo: include `window.location.origin` e le porte dev comuni (3000, 5173, 8080) sia su `localhost` che `127.0.0.1`. `maxAge: 86400`.
`createCustomAdapter`	`(config: CorsConfig) => ICorsAdapter`	Adapter con configurazione fornita esplicitamente.

Esempi

Single origin (produzione)

import { CorsAdapter } from '@pzeta/postgrest'

const adapter = new CorsAdapter({
  allowedOrigins: ['https://app.example.com'],
  allowedMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  allowCredentials: false,
  maxAge: 3600,
})

const client = adapter.createCorsEnabledClient({
  baseURL: 'https://api.example.com',
  timeout: 10000,
})

const { data } = await client.get('/users')

Multi-origin con credentials

import { CorsAdapterFactory } from '@pzeta/postgrest'

const adapter = CorsAdapterFactory.createCustomAdapter({
  allowedOrigins: [
    'https://app.example.com',
    'https://admin.example.com',
  ],
  allowedMethods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-Id'],
  allowCredentials: true,
  maxAge: 3600,
  exposedHeaders: ['X-Total-Count', 'X-Page-Count'],
})

const client = adapter.createCorsEnabledClient({ baseURL: '/api' })

Default per sviluppo

import { CorsAdapterFactory } from '@pzeta/postgrest'

// Permette automaticamente localhost:3000, :5173, :8080 (+ 127.0.0.1)
const adapter = CorsAdapterFactory.createDefaultAdapter()

const client = adapter.createCorsEnabledClient({
  baseURL: 'http://localhost:8000',
})

createDefaultAdapter è pensato per ambienti di sviluppo locali. In produzione usa sempre createCustomAdapter con una whitelist esplicita di origin trusted.

Integrazione con AxiosHttpClient

import { CorsAdapterFactory, AxiosHttpClient } from '@pzeta/postgrest'

const corsAdapter = CorsAdapterFactory.createCustomAdapter({
  allowedOrigins: ['https://app.example.com'],
  allowedMethods: ['GET', 'POST', 'PUT', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization'],
  allowCredentials: true,
})

const axiosInstance = corsAdapter.createCorsEnabledClient({
  baseURL: 'https://api.example.com',
})

const httpClient = new AxiosHttpClient(axiosInstance)

Tipi correlati

AxiosHttpClient — client che può consumare l'AxiosInstance prodotta dall'adapter
StrategyAwareHttpClient — accetta la stessa AxiosInstance per combinare CORS e auth strategy
HttpClientFactory — alternativa di alto livello per setup standard

AxiosHttpClient

Client HTTP basato su Axios (peer dependency opzionale). Ideale quando servono interceptors, progress tracking o quando il progetto già usa Axios.

FetchHttpClient

Client HTTP zero-dipendenze basato su Fetch API nativa. Compatibile con interfaccia Axios tramite FetchAdapter. Supporta auth strategy, retry su 401 e timeout.