kimu-core 0.4.1

package/src/modules-repository/api-core/README.md

@@ -0,0 +1,435 @@
+# KIMU API Core Module
+
+Modulo minimale per la gestione di richieste HTTP verso API esterne, basato su `fetch` nativo.
+
+## Caratteristiche
+
+- ✅ Zero dipendenze esterne
+- ✅ Basato su fetch API nativa
+- ✅ Promise-based (async/await)
+- ✅ TypeScript-first con type safety completo
+- ✅ Supporto per tutti i metodi HTTP (GET, POST, PUT, PATCH, DELETE)
+- ✅ Gestione automatica di query parameters, headers, body
+- ✅ Interceptor per request/response/error
+- ✅ Timeout configurabile
+- ✅ Gestione errori strutturata
+- ✅ Supporto per diversi tipi di risposta (JSON, text, blob, arraybuffer)
+- ✅ BaseURL globale configurabile
+- ✅ Lightweight (~2KB minified)
+
+## Installazione
+
+Il modulo è incluso nel repository `kimu-modules`. Per installarlo:
+
+```bash
+# Usando kimu-cli (quando disponibile)
+kimu install module api-core
+
+# Manualmente
+# Copia la cartella src/modules/api-core nel tuo progetto
+```
+
+## Utilizzo Base
+
+### Inizializzazione
+
+```typescript
+import { KimuModuleManager } from '@kimu/core';
+import ApiCoreModule from './modules/api-core/module';
+
+// Inizializza il modulo
+const moduleManager = KimuModuleManager.getInstance();
+const apiModule = new ApiCoreModule();
+await moduleManager.loadModule(apiModule);
+
+// Ottieni il servizio
+const api = moduleManager.getService('api-core');
+```
+
+### Configurazione Globale
+
+```typescript
+import { apiCoreService } from './modules/api-core/api-core-service';
+
+// Configura baseURL e headers di default
+apiCoreService.configure({
+  baseURL: 'https://api.example.com',
+  timeout: 10000, // 10 secondi
+  headers: {
+    'Authorization': 'Bearer YOUR_TOKEN',
+    'X-Custom-Header': 'value'
+  }
+});
+```
+
+### Richieste GET
+
+```typescript
+// GET semplice
+const response = await api.get('/users');
+console.log(response.data); // Array di utenti
+
+// GET con query parameters
+const response = await api.get('/users', {
+  params: {
+    page: 1,
+    limit: 10,
+    sort: 'name'
+  }
+});
+
+// GET con headers custom
+const response = await api.get('/users', {
+  headers: {
+    'Accept-Language': 'it-IT'
+  }
+});
+```
+
+### Richieste POST
+
+```typescript
+// POST con JSON body
+const response = await api.post('/users', {
+  name: 'Mario Rossi',
+  email: 'mario@example.com',
+  age: 30
+});
+
+// POST con FormData
+const formData = new FormData();
+formData.append('file', fileInput.files[0]);
+formData.append('title', 'My File');
+
+const response = await api.post('/upload', formData);
+```
+
+### Altri Metodi HTTP
+
+```typescript
+// PUT - aggiorna risorsa
+const response = await api.put('/users/123', {
+  name: 'Mario Rossi Updated'
+});
+
+// PATCH - aggiorna parzialmente
+const response = await api.patch('/users/123', {
+  age: 31
+});
+
+// DELETE - elimina risorsa
+const response = await api.delete('/users/123');
+```
+
+### Richiesta Generica
+
+```typescript
+const response = await api.request('/custom-endpoint', {
+  method: 'POST',
+  body: { key: 'value' },
+  headers: { 'X-Custom': 'header' },
+  params: { filter: 'active' },
+  timeout: 5000,
+  responseType: 'json'
+});
+```
+
+## Gestione Errori
+
+```typescript
+try {
+  const response = await api.get('/users');
+  console.log(response.data);
+} catch (error) {
+  console.error('Error:', error.message);
+  console.error('Status:', error.status);
+  console.error('Status Text:', error.statusText);
+  console.error('Response Data:', error.data);
+}
+```
+
+## Interceptor
+
+### Request Interceptor
+
+```typescript
+apiCoreService.configure({
+  requestInterceptor: (config) => {
+    // Aggiungi token dinamicamente
+    const token = localStorage.getItem('token');
+    if (token) {
+      config.headers = {
+        ...config.headers,
+        'Authorization': `Bearer ${token}`
+      };
+    }
+    
+    // Log della richiesta
+    console.log('Making request:', config);
+    
+    return config;
+  }
+});
+```
+
+### Response Interceptor
+
+```typescript
+apiCoreService.configure({
+  responseInterceptor: (response) => {
+    // Log della risposta
+    console.log('Response received:', response.status);
+    
+    // Trasforma i dati
+    response.data = {
+      ...response.data,
+      receivedAt: new Date().toISOString()
+    };
+    
+    return response;
+  }
+});
+```
+
+### Error Interceptor
+
+```typescript
+apiCoreService.configure({
+  errorInterceptor: async (error) => {
+    // Gestione errore 401: refresh token
+    if (error.status === 401) {
+      const newToken = await refreshToken();
+      localStorage.setItem('token', newToken);
+      
+      // Puoi anche rilanciare una richiesta o modificare l'errore
+      error.message = 'Session expired, please login again';
+    }
+    
+    // Log errori
+    console.error('API Error:', error);
+    
+    return error;
+  }
+});
+```
+
+## Timeout e Cancellazione
+
+```typescript
+// Timeout automatico
+const response = await api.get('/slow-endpoint', {
+  timeout: 3000 // 3 secondi
+});
+
+// Cancellazione manuale con AbortController
+const controller = new AbortController();
+
+const request = api.get('/data', {
+  signal: controller.signal
+});
+
+// Cancella dopo 2 secondi
+setTimeout(() => controller.abort(), 2000);
+
+try {
+  const response = await request;
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request was cancelled');
+  }
+}
+```
+
+## Tipi di Risposta
+
+```typescript
+// JSON (default)
+const response = await api.get('/users', {
+  responseType: 'json'
+});
+
+// Testo
+const response = await api.get('/readme.txt', {
+  responseType: 'text'
+});
+console.log(response.data); // stringa
+
+// Blob (per file)
+const response = await api.get('/image.png', {
+  responseType: 'blob'
+});
+const imageUrl = URL.createObjectURL(response.data);
+
+// ArrayBuffer (per dati binari)
+const response = await api.get('/binary-data', {
+  responseType: 'arraybuffer'
+});
+```
+
+## Uso in Componenti KIMU
+
+```typescript
+import { KimuComponentElement } from '@kimu/core';
+import { KimuModuleManager } from '@kimu/core';
+
+export class UserListComponent extends KimuComponentElement {
+  private api: any;
+  private users: any[] = [];
+
+  async onInit() {
+    // Ottieni il servizio API
+    this.api = KimuModuleManager.getInstance().getService('api-core');
+    
+    // Carica i dati
+    await this.loadUsers();
+  }
+
+  async loadUsers() {
+    try {
+      const response = await this.api.get('/users');
+      this.users = response.data;
+      this.onRender();
+    } catch (error) {
+      console.error('Failed to load users:', error);
+    }
+  }
+
+  async createUser(userData: any) {
+    try {
+      const response = await this.api.post('/users', userData);
+      this.users.push(response.data);
+      this.onRender();
+    } catch (error) {
+      console.error('Failed to create user:', error);
+    }
+  }
+}
+```
+
+## TypeScript Support
+
+Il modulo è completamente tipizzato:
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+// Type-safe request
+const response = await api.get<User[]>('/users');
+response.data.forEach(user => {
+  console.log(user.name); // Type-safe access
+});
+
+// Type-safe POST
+const newUser: Omit<User, 'id'> = {
+  name: 'Mario',
+  email: 'mario@example.com'
+};
+
+const response = await api.post<User>('/users', newUser);
+console.log(response.data.id); // Type-safe
+```
+
+## Best Practices
+
+### 1. Configura baseURL globalmente
+```typescript
+apiCoreService.configure({
+  baseURL: process.env.API_URL || 'https://api.example.com'
+});
+```
+
+### 2. Usa interceptor per autenticazione
+```typescript
+apiCoreService.configure({
+  requestInterceptor: (config) => {
+    const token = getAuthToken();
+    if (token) {
+      config.headers = {
+        ...config.headers,
+        'Authorization': `Bearer ${token}`
+      };
+    }
+    return config;
+  }
+});
+```
+
+### 3. Gestisci errori globalmente
+```typescript
+apiCoreService.configure({
+  errorInterceptor: (error) => {
+    if (error.status === 401) {
+      // Redirect to login
+      window.location.href = '/login';
+    } else if (error.status >= 500) {
+      // Show error notification
+      showNotification('Server error, please try again later');
+    }
+    return error;
+  }
+});
+```
+
+### 4. Crea wrapper service per API specifiche
+```typescript
+class UserService {
+  private api = apiCoreService;
+
+  async getUsers() {
+    return this.api.get<User[]>('/users');
+  }
+
+  async getUser(id: number) {
+    return this.api.get<User>(`/users/${id}`);
+  }
+
+  async createUser(user: Omit<User, 'id'>) {
+    return this.api.post<User>('/users', user);
+  }
+
+  async updateUser(id: number, user: Partial<User>) {
+    return this.api.patch<User>(`/users/${id}`, user);
+  }
+
+  async deleteUser(id: number) {
+    return this.api.delete(`/users/${id}`);
+  }
+}
+```
+
+## Confronto con Altri Framework
+
+| Feature | KIMU api-core | Angular HttpClient | Axios | Fetch nativo |
+|---------|---------------|-------------------|-------|--------------|
+| Bundle Size | ~2KB | ~40KB | ~13KB | 0KB (nativo) |
+| Dependencies | 0 | RxJS required | 0 | 0 |
+| TypeScript | ✅ Native | ✅ Native | ✅ Native | ⚠️ Basic |
+| Interceptors | ✅ | ✅ | ✅ | ❌ |
+| Timeout | ✅ | ✅ | ✅ | ⚠️ Manual |
+| Query Params | ✅ Auto | ✅ Auto | ✅ Auto | ❌ Manual |
+| Error Handling | ✅ Structured | ✅ Structured | ✅ Structured | ⚠️ Basic |
+| Promise/Observable | Promise | Observable | Promise | Promise |
+
+## Roadmap
+
+- [ ] Support per retry automatico
+- [ ] Caching integrato delle richieste
+- [ ] Request deduplication
+- [ ] Upload progress tracking
+- [ ] Download progress tracking
+- [ ] Request queue con priorità
+- [ ] Mock/test utilities
+
+## License
+
+Questo modulo fa parte di KIMU-Core ed è distribuito sotto licenza MPL-2.0.
+
+## Supporto
+
+Per issue, feature request o domande:
+- GitHub Issues: [kimu-core/issues](https://github.com/UnicoVerso/kimu-core/issues)
+- Documentazione: [kimu-docs](https://github.com/UnicoVerso/kimu-docs)

package/src/modules-repository/api-core/api-core-service.ts

@@ -0,0 +1,289 @@
+/**
+ * KIMU API Core Service
+ * Lightweight HTTP client based on native fetch API
+ * Zero dependencies, Promise-based, TypeScript-first
+ */
+
+import {
+  ApiRequestOptions,
+  ApiResponse,
+  ApiError,
+  ApiConfig
+} from './interfaces';
+
+/**
+ * Main API service class for making HTTP requests
+ */
+export class ApiCoreService {
+  private config: ApiConfig = {};
+
+  /**
+   * Configure the API service with global settings
+   * @param config - Global configuration options
+   */
+  configure(config: ApiConfig): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Make a GET request
+   * @param url - Request URL (relative to baseURL if configured)
+   * @param options - Request options
+   * @returns Promise with response data
+   */
+  async get<T = any>(url: string, options?: ApiRequestOptions): Promise<ApiResponse<T>> {
+    return this.request<T>(url, { ...options, method: 'GET' });
+  }
+
+  /**
+   * Make a POST request
+   * @param url - Request URL
+   * @param data - Request body data
+   * @param options - Request options
+   * @returns Promise with response data
+   */
+  async post<T = any>(url: string, data?: any, options?: ApiRequestOptions): Promise<ApiResponse<T>> {
+    return this.request<T>(url, { ...options, method: 'POST', body: data });
+  }
+
+  /**
+   * Make a PUT request
+   * @param url - Request URL
+   * @param data - Request body data
+   * @param options - Request options
+   * @returns Promise with response data
+   */
+  async put<T = any>(url: string, data?: any, options?: ApiRequestOptions): Promise<ApiResponse<T>> {
+    return this.request<T>(url, { ...options, method: 'PUT', body: data });
+  }
+
+  /**
+   * Make a PATCH request
+   * @param url - Request URL
+   * @param data - Request body data
+   * @param options - Request options
+   * @returns Promise with response data
+   */
+  async patch<T = any>(url: string, data?: any, options?: ApiRequestOptions): Promise<ApiResponse<T>> {
+    return this.request<T>(url, { ...options, method: 'PATCH', body: data });
+  }
+
+  /**
+   * Make a DELETE request
+   * @param url - Request URL
+   * @param options - Request options
+   * @returns Promise with response data
+   */
+  async delete<T = any>(url: string, options?: ApiRequestOptions): Promise<ApiResponse<T>> {
+    return this.request<T>(url, { ...options, method: 'DELETE' });
+  }
+
+  /**
+   * Make a generic HTTP request
+   * @param url - Request URL
+   * @param options - Request options
+   * @returns Promise with response data
+   */
+  async request<T = any>(url: string, options: ApiRequestOptions = {}): Promise<ApiResponse<T>> {
+    try {
+      // Apply request interceptor if configured
+      let finalOptions = options;
+      if (this.config.requestInterceptor) {
+        finalOptions = await this.config.requestInterceptor(options);
+      }
+
+      // Build final URL with baseURL and query params
+      const finalUrl = this.buildUrl(url, finalOptions.params);
+
+      // Build headers
+      const headers = this.buildHeaders(finalOptions);
+
+      // Build request body
+      const body = this.buildBody(finalOptions.body, headers);
+
+      // Setup timeout if specified
+      const controller = new AbortController();
+      const signal = finalOptions.signal || controller.signal;
+      const timeout = finalOptions.timeout || this.config.timeout;
+      
+      let timeoutId: NodeJS.Timeout | undefined;
+      if (timeout) {
+        timeoutId = setTimeout(() => controller.abort(), timeout);
+      }
+
+      // Make fetch request
+      const response = await fetch(finalUrl, {
+        method: finalOptions.method || 'GET',
+        headers,
+        body,
+        credentials: finalOptions.credentials,
+        cache: finalOptions.cache,
+        signal
+      });
+
+      // Clear timeout
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+
+      // Parse response
+      const responseData = await this.parseResponse<T>(response, finalOptions.responseType);
+
+      // Build API response object
+      let apiResponse: ApiResponse<T> = {
+        data: responseData,
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+        raw: response
+      };
+
+      // Apply response interceptor if configured
+      if (this.config.responseInterceptor) {
+        apiResponse = await this.config.responseInterceptor(apiResponse);
+      }
+
+      // Check if response is ok
+      if (!response.ok) {
+        throw this.createError(
+          `HTTP Error ${response.status}: ${response.statusText}`,
+          response.status,
+          response.statusText,
+          responseData
+        );
+      }
+
+      return apiResponse;
+
+    } catch (error: any) {
+      // Create API error
+      let apiError: ApiError;
+      
+      if (error.name === 'AbortError') {
+        apiError = this.createError('Request timeout', undefined, undefined, undefined, error);
+      } else if (error.message?.includes('HTTP Error')) {
+        apiError = error;
+      } else {
+        apiError = this.createError(
+          error.message || 'Network error',
+          undefined,
+          undefined,
+          undefined,
+          error
+        );
+      }
+
+      // Apply error interceptor if configured
+      if (this.config.errorInterceptor) {
+        apiError = await this.config.errorInterceptor(apiError);
+      }
+
+      throw apiError;
+    }
+  }
+
+  /**
+   * Build final URL with baseURL and query parameters
+   */
+  private buildUrl(url: string, params?: Record<string, string | number | boolean>): string {
+    let finalUrl = url;
+
+    // Add baseURL if configured and URL is relative
+    if (this.config.baseURL && !url.startsWith('http')) {
+      finalUrl = `${this.config.baseURL.replace(/\/$/, '')}/${url.replace(/^\//, '')}`;
+    }
+
+    // Add query parameters
+    if (params) {
+      const queryString = Object.entries(params)
+        .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+        .join('&');
+      
+      finalUrl += (finalUrl.includes('?') ? '&' : '?') + queryString;
+    }
+
+    return finalUrl;
+  }
+
+  /**
+   * Build request headers
+   */
+  private buildHeaders(options: ApiRequestOptions): HeadersInit {
+    const headers: Record<string, string> = {
+      ...this.config.headers,
+      ...options.headers
+    };
+
+    // Auto-add Content-Type for JSON body if not specified
+    if (options.body && typeof options.body === 'object' && !headers['Content-Type']) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    return headers;
+  }
+
+  /**
+   * Build request body
+   */
+  private buildBody(body: any, _headers: HeadersInit): BodyInit | undefined {
+    if (!body) {
+      return undefined;
+    }
+
+    // If body is already a string, FormData, Blob, etc., return as-is
+    if (typeof body === 'string' || body instanceof FormData || body instanceof Blob) {
+      return body;
+    }
+
+    // Otherwise, stringify as JSON
+    return JSON.stringify(body);
+  }
+
+  /**
+   * Parse response based on response type
+   */
+  private async parseResponse<T>(response: Response, responseType?: string): Promise<T> {
+    const type = responseType || 'json';
+
+    switch (type) {
+      case 'json':
+        try {
+          return await response.json();
+        } catch {
+          return null as T;
+        }
+      case 'text':
+        return await response.text() as T;
+      case 'blob':
+        return await response.blob() as T;
+      case 'arraybuffer':
+        return await response.arrayBuffer() as T;
+      default:
+        return await response.json();
+    }
+  }
+
+  /**
+   * Create an API error object
+   */
+  private createError(
+    message: string,
+    status?: number,
+    statusText?: string,
+    data?: any,
+    originalError?: Error
+  ): ApiError {
+    return {
+      message,
+      status,
+      statusText,
+      data,
+      originalError: originalError || new Error(message)
+    };
+  }
+}
+
+/**
+ * Singleton instance of API Core Service
+ */
+export const apiCoreService = new ApiCoreService();