@zerosls/clm-sdk 1.0.0

package/.docs/publicacion-npm.md

@@ -0,0 +1,111 @@
+# Guía de Publicación del SDK
+
+Este documento describe el proceso para publicar nuevas versiones del SDK en npm usando GitLab CI.
+
+## Requisitos previos
+
+- Token NPM configurado en GitLab CI/CD Variables como `NPM_TOKEN`
+- Archivo `.gitlab-ci.yml` correctamente configurado
+
+## Proceso de publicación
+
+### 1. Desarrollo y pruebas
+
+```bash
+# Instalar dependencias
+npm install
+
+# Ejecutar pruebas
+npm test
+
+# Desarrollo con enlace local
+npm link               # En el SDK
+npm link @zero/clm-sdk # En el proyecto frontend
+```
+
+### 2. Actualizar versión
+
+```bash
+# Incremento de versión patch (1.0.0 -> 1.0.1)
+npm version patch
+
+# Incremento de versión minor (1.0.0 -> 1.1.0)
+npm version minor
+
+# Incremento de versión major (1.0.0 -> 2.0.0)
+npm version major
+```
+
+Estos comandos:
+- Actualizan la versión en `package.json`
+- Crean un commit con el cambio
+- Crean un tag con formato `v1.0.0`
+
+### 3. Publicar a GitLab y npm
+
+```bash
+# Enviar cambios y tags a GitLab
+git push --follow-tags
+```
+
+El pipeline de GitLab CI se activará automáticamente cuando detecte un tag con formato `v*`, compilando y publicando el paquete en npm.
+
+### 4. Verificar publicación
+
+Verificar que la nueva versión aparece en npm:
+
+```bash
+npm view @zero/clm-sdk versions
+```
+
+## Gestión de tags
+
+### Crear tag manualmente
+
+```bash
+# Crear tag
+git tag v1.0.1
+
+# Enviar tag a GitLab
+git push origin v1.0.1
+```
+
+### Eliminar tag (si es necesario)
+
+```bash
+# Eliminar tag local
+git tag -d v1.0.1
+
+# Eliminar tag en GitLab
+git push origin :refs/tags/v1.0.1
+```
+
+## Desarrollo con npm link
+
+Para desarrollar el SDK mientras se prueba en un proyecto frontend:
+
+```bash
+# En el directorio del SDK
+npm link
+npm run dev
+
+# En el directorio del frontend
+npm link @zero/clm-sdk
+```
+
+Para desconectar:
+
+```bash
+# En el directorio del frontend
+npm unlink --no-save @zero/clm-sdk
+npm install
+```
+
+## Solución de problemas
+
+### Fallo en la publicación
+
+1. Verificar logs en GitLab CI
+2. Comprobar que el token NPM es válido y está configurado correctamente
+3. Asegurar que la versión no existe ya en npm
+```

package/.env.example

@@ -0,0 +1,14 @@
+# Base URL configuration
+SDK_BASE_URL=https://dev-api.zeroclm.io/zeroclm-api
+SDK_DEFAULT_ORGANIZATION=default-org
+
+# Cache settings
+SDK_CACHE_TTL=60000
+
+# Version information
+SDK_VERSION=1.0.0
+
+# API endpoints
+SDK_AUTH_ENDPOINT=/auth
+SDK_USERS_ENDPOINT=/users
+SDK_SETTINGS_ENDPOINT=/settings

package/.gitlab-ci.yml

@@ -0,0 +1,23 @@
+stages:
+  - build
+  - publish
+
+build:
+  stage: build
+  image: node:latest
+  script:
+    - npm ci
+    - npm run build
+  artifacts:
+    paths:
+      - dist/
+
+publish:
+  stage: publish
+  image: node:latest
+  script:
+    - npm ci
+    - echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
+    - npm publish --access public
+  rules:
+    - if: $CI_COMMIT_BRANCH == "main"

package/README.md

@@ -0,0 +1,202 @@
+# CLM SDK
+
+Cliente TypeScript para consumir la API de ZeroCLM.
+
+## Instalación
+
+```bash
+npm install @zero/clm-sdk
+```
+
+## Uso básico
+
+```typescript
+import { ClmSdk } from '@zero/clm-sdk';
+
+// Crear instancia del SDK
+const sdk = new ClmSdk({
+  baseUrl: 'https://api.clm-app.com/api',  // URL base de la API
+  organization: 'mi-organizacion',        // ID de organización
+  token: 'jwt-token-opcional'             // Token JWT (opcional)
+});
+
+// Login
+async function login() {
+  try {
+    const response = await sdk.auth.login({
+      email: 'usuario@ejemplo.com',
+      password: 'contraseña'
+    });
+    
+    console.log('Usuario logueado:', response.user);
+    // El token se establece automáticamente para futuras peticiones
+  } catch (error) {
+    console.error('Error de login:', error);
+  }
+}
+
+// Obtener configuraciones
+async function getSettings() {
+  try {
+    const settings = await sdk.settings.getAll({
+      group: 'general',
+      enabled: true
+    });
+    
+    console.log('Configuraciones:', settings);
+  } catch (error) {
+    console.error('Error al obtener configuraciones:', error);
+  }
+}
+```
+
+## Módulos disponibles
+
+### Auth
+
+Gestión de autenticación y tokens:
+
+```typescript
+// Login
+const loginResponse = await sdk.auth.login({ email, password });
+
+// Refresh token
+const refreshResponse = await sdk.auth.refreshToken({ refreshToken });
+
+// Logout
+await sdk.auth.logout();
+
+// Verificar si está autenticado
+const isAuthenticated = sdk.auth.isAuthenticated();
+```
+
+### Settings
+
+Gestión de configuraciones:
+
+```typescript
+// Obtener todas las configuraciones
+const settings = await sdk.settings.getAll();
+
+// Obtener configuración por ID
+const setting = await sdk.settings.getById('config-id');
+
+// Obtener por grupo y nombre
+const appName = await sdk.settings.getByName('general', 'app_name');
+
+// Crear configuración
+const newSetting = await sdk.settings.create({
+  group_name: 'app',
+  name: 'theme',
+  value: 'dark',
+  data_type: 'string',
+  description: 'Tema de la aplicación'
+});
+
+// Actualizar configuración
+await sdk.settings.update('config-id', { value: 'nuevo-valor' });
+
+// Activar/desactivar configuración
+await sdk.settings.toggleEnabled('config-id', true);
+
+// Eliminar configuración
+await sdk.settings.delete('config-id');
+```
+
+## Manejo de errores
+
+El SDK incluye un sistema de manejo de errores personalizado:
+
+```typescript
+import { ApiError, ErrorType } from '@zero/clm-sdk';
+
+try {
+  await sdk.settings.getById('id-inexistente');
+} catch (error) {
+  if (error instanceof ApiError) {
+    console.log('Código de estado:', error.statusCode);
+    console.log('Tipo de error:', error.type);
+    console.log('Es error de autenticación:', error.isAuthenticationError);
+    console.log('Detalles:', error.details);
+  }
+}
+```
+
+## Eventos
+
+El SDK emite eventos que puedes escuchar:
+
+```typescript
+// Escuchar cambios de token
+const subscription = sdk.on('tokenChanged', (token) => {
+  console.log('Token cambiado:', token);
+});
+
+// Escuchar errores de autenticación
+sdk.on('authError', (error) => {
+  console.log('Error de autenticación:', error);
+  // Redirigir a login, etc.
+});
+
+// Cancelar suscripción cuando ya no sea necesaria
+subscription.unsubscribe();
+```
+
+## Caché
+
+El SDK incluye un sistema de caché para optimizar peticiones:
+
+```typescript
+// Limpiar toda la caché
+sdk.cache.clear();
+
+// Limpiar sólo caché de settings
+sdk.cache.clearByPrefix('/settings');
+```
+
+## Configuración avanzada
+
+```typescript
+const sdk = new ClmSdk({
+  baseUrl: 'https://api.clm-app.com/api',
+  organization: 'mi-organizacion',
+  cache: {
+    enabled: true,    // Activar/desactivar caché
+    ttl: 60000        // Tiempo de vida en ms (default: 1 minuto)
+  },
+  debug: true         // Activar logs de depuración
+});
+```
+
+## Desarrollo
+
+### Instalación de dependencias
+
+```bash
+npm install
+```
+
+### Ejecutar tests
+
+```bash
+npm test               # Ejecutar tests
+npm run test:watch     # Ejecutar tests en modo watch
+npm run test:coverage  # Generar reporte de cobertura
+```
+
+### Compilación
+
+```bash
+npm run build          # Compilar a JavaScript
+npm run dev            # Compilar en modo watch
+```
+
+### Lint
+
+```bash
+npm run lint
+```
+
+## Licencia
+
+MIT

package/dist/config/config.d.ts

@@ -0,0 +1,3 @@
+import { SdkConfig } from "../types/sdk";
+export declare const DEFAULT_CONFIG: Partial<SdkConfig>;
+export declare function mergeWithDefaultConfig(config: Partial<SdkConfig>): SdkConfig;

package/dist/config/config.js

@@ -0,0 +1,21 @@
+// Valores por defecto para la configuración
+export const DEFAULT_CONFIG = {
+    baseUrl: "https://api.clm-app.com/api",
+    organization: "default-org",
+    cache: {
+        enabled: true,
+        ttl: 60000, // 1 minuto
+    },
+    debug: true,
+};
+// Función para combinar configuración del usuario con valores por defecto
+export function mergeWithDefaultConfig(config) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...config,
+        cache: {
+            ...DEFAULT_CONFIG.cache,
+            ...(config.cache || {}), // Usar un objeto vacío si config.cache es undefined
+        },
+    };
+}

package/dist/core/api-client.d.ts

@@ -0,0 +1,27 @@
+import { SdkConfig } from "../types/sdk";
+import { RequestOptions } from "../types/common";
+import { EventEmitter } from "./event-emitter";
+export declare class ApiClient {
+    private baseUrl;
+    private organization;
+    private token;
+    private eventEmitter;
+    private cache;
+    private debug;
+    private cacheEnabled;
+    constructor(config: SdkConfig, eventEmitter: EventEmitter);
+    setToken(token: string | null): void;
+    getToken(): string | null;
+    setOrganization(organization: string): void;
+    get<T>(endpoint: string, params?: Record<string, any>, options?: RequestOptions): Promise<T>;
+    post<T>(endpoint: string, data?: any, options?: RequestOptions): Promise<T>;
+    patch<T>(endpoint: string, data?: any, options?: RequestOptions): Promise<T>;
+    put<T>(endpoint: string, data?: any, options?: RequestOptions): Promise<T>;
+    delete<T>(endpoint: string, data?: any, // ✅ Cambiar params por data para enviarlo en el body
+    options?: RequestOptions): Promise<T>;
+    /**
+     * Invalida la caché relacionada con un endpoint específico
+     */
+    private invalidateCache;
+    private request;
+}

package/dist/core/api-client.js

@@ -0,0 +1,183 @@
+import { ApiError } from "./api-error";
+import { Cache } from "../utils/cache";
+import { buildUrl, buildHeaders, generateCacheKey, parseResponse, } from "../utils/http";
+export class ApiClient {
+    constructor(config, eventEmitter) {
+        var _a, _b;
+        this.token = null;
+        this.baseUrl = config.baseUrl;
+        this.organization = config.organization;
+        this.token = config.token || null;
+        this.eventEmitter = eventEmitter;
+        this.cacheEnabled = ((_a = config.cache) === null || _a === void 0 ? void 0 : _a.enabled) !== false;
+        this.cache = new Cache((_b = config.cache) === null || _b === void 0 ? void 0 : _b.ttl);
+        this.debug = config.debug || false;
+    }
+    // Métodos para gestión del token
+    setToken(token) {
+        this.token = token;
+        this.eventEmitter.emit("tokenChanged", token);
+    }
+    getToken() {
+        return this.token;
+    }
+    setOrganization(organization) {
+        this.organization = organization;
+    }
+    // Método GET
+    async get(endpoint, params, options) {
+        return this.request("GET", endpoint, undefined, params, options);
+    }
+    // Método POST
+    async post(endpoint, data, options) {
+        return this.request("POST", endpoint, data, undefined, options);
+    }
+    // Método PATCH
+    async patch(endpoint, data, options) {
+        const result = await this.request("PATCH", endpoint, data, undefined, options);
+        this.invalidateCache(endpoint);
+        return result;
+    }
+    // Método PUT
+    async put(endpoint, data, options) {
+        const result = await this.request("PUT", endpoint, data, undefined, options);
+        this.invalidateCache(endpoint);
+        return result;
+    }
+    // ✅ Método DELETE - CORREGIDO
+    async delete(endpoint, data, // ✅ Cambiar params por data para enviarlo en el body
+    options) {
+        console.log("🗑️ DELETE request:", { endpoint, data });
+        const result = await this.request("DELETE", endpoint, data, // ✅ Enviar como body (data)
+        undefined, // ✅ params es undefined
+        options);
+        this.invalidateCache(endpoint);
+        console.log("✅ DELETE response:", result);
+        return result;
+    }
+    /**
+     * Invalida la caché relacionada con un endpoint específico
+     */
+    invalidateCache(endpoint) {
+        if (this.cacheEnabled) {
+            const basePath = endpoint.split("/").slice(0, 2).join("/");
+            this.cache.clearByPrefix(`GET:${this.baseUrl}${basePath}`);
+            if (this.debug) {
+                console.log(`[SDK-Cache] Invalidated cache for: ${basePath}`);
+            }
+        }
+    }
+    // Método central para todas las peticiones HTTP
+    async request(method, endpoint, data, params, options = {}) {
+        const url = buildUrl(this.baseUrl, endpoint, params);
+        // =====================================================
+        // 1. Construir headers base
+        // =====================================================
+        const base = buildHeaders(this.token, {
+            "X-Organization": this.organization,
+            ...(options.headers || {}),
+        });
+        const headers = new Headers(base);
+        if (!this.token) {
+            headers.delete("Authorization");
+        }
+        // =====================================================
+        // 2. Si el endpoint es /legacy/** → agregar Bearer legacy
+        // =====================================================
+        if (endpoint.startsWith("/legacy/")) {
+            const legacyToken = window.__LEGACY_TOKEN__ ||
+                sessionStorage.getItem("legacy_token") ||
+                null;
+            if (legacyToken) {
+                headers.set("Authorization", `Bearer ${legacyToken}`);
+            }
+        }
+        // =====================================================
+        // 3. Cache
+        // =====================================================
+        const useCache = this.cacheEnabled && options.useCache !== false;
+        if (useCache && method === "GET") {
+            const cacheKey = generateCacheKey(method, url, data);
+            const cachedData = this.cache.get(cacheKey);
+            if (cachedData) {
+                if (this.debug) {
+                    console.log(`[SDK-Cache] Hit: ${cacheKey}`);
+                }
+                return cachedData;
+            }
+        }
+        this.eventEmitter.emit("beforeRequest", {
+            url,
+            method,
+            data,
+        });
+        try {
+            // =====================================================
+            // 4. Preparar options de fetch
+            // =====================================================
+            const fetchOptions = {
+                method,
+                headers,
+                credentials: "include",
+            };
+            // ✅ CRÍTICO: Agregar body para POST, PUT, PATCH y DELETE
+            if (data && method !== "GET") {
+                fetchOptions.body = JSON.stringify(data);
+                console.log(`📤 ${method} Body:`, data);
+            }
+            // =====================================================
+            // 5. Hacer la llamada real
+            // =====================================================
+            console.log(`🌐 ${method} ${url}`, fetchOptions);
+            const response = await fetch(url, fetchOptions);
+            // Manejo de errores HTTP
+            if (!response.ok) {
+                let errorData;
+                try {
+                    errorData = await response.json();
+                }
+                catch (_a) {
+                    errorData = { message: response.statusText };
+                }
+                console.error(`❌ ${method} ${response.status}:`, errorData);
+                if (response.status === 401) {
+                    this.eventEmitter.emit("authError", {
+                        statusCode: 401,
+                        message: errorData.message || "Authentication required",
+                    });
+                }
+                return errorData;
+            }
+            // Parsear respuesta exitosa
+            const responseData = await parseResponse(response);
+            // Guardar en caché si aplica
+            if (useCache && method === "GET") {
+                const cacheKey = generateCacheKey(method, url, data);
+                const cacheTime = options.cacheTime || undefined;
+                this.cache.set(cacheKey, responseData, cacheTime);
+                if (this.debug) {
+                    console.log(`[SDK-Cache] Set: ${cacheKey}`);
+                }
+            }
+            this.eventEmitter.emit("afterRequest", {
+                url,
+                method,
+                response: responseData,
+            });
+            return responseData;
+        }
+        catch (error) {
+            this.eventEmitter.emit("requestError", {
+                url,
+                method,
+                error,
+            });
+            if (error instanceof ApiError) {
+                throw error;
+            }
+            throw new ApiError(error.message || "Network error", 0, {
+                originalError: error,
+            });
+        }
+    }
+}

package/dist/core/api-error.d.ts

@@ -0,0 +1,15 @@
+import { ErrorType } from '../types/sdk';
+export declare class ApiError extends Error {
+    readonly isApiError = true;
+    readonly statusCode: number;
+    readonly type: ErrorType;
+    readonly details?: any;
+    constructor(message: string, statusCode: number, details?: any);
+    private determineErrorType;
+    get isNetworkError(): boolean;
+    get isAuthenticationError(): boolean;
+    get isAuthorizationError(): boolean;
+    get isNotFoundError(): boolean;
+    get isValidationError(): boolean;
+    get isServerError(): boolean;
+}

package/dist/core/api-error.js

@@ -0,0 +1,46 @@
+import { ErrorType } from '../types/sdk';
+export class ApiError extends Error {
+    constructor(message, statusCode, details) {
+        super(message);
+        this.isApiError = true;
+        this.name = 'ApiError';
+        this.statusCode = statusCode;
+        this.details = details;
+        this.type = this.determineErrorType(statusCode);
+        // Para que instanceof funcione correctamente con clases extendidas
+        Object.setPrototypeOf(this, ApiError.prototype);
+    }
+    // Determina el tipo de error según el código HTTP
+    determineErrorType(statusCode) {
+        if (statusCode === 401)
+            return ErrorType.AUTHENTICATION;
+        if (statusCode === 403)
+            return ErrorType.AUTHORIZATION;
+        if (statusCode === 404)
+            return ErrorType.NOT_FOUND;
+        if (statusCode >= 400 && statusCode < 500)
+            return ErrorType.VALIDATION;
+        if (statusCode >= 500)
+            return ErrorType.SERVER;
+        return ErrorType.UNKNOWN;
+    }
+    // Propiedades útiles para verificación de tipo de error
+    get isNetworkError() {
+        return this.type === ErrorType.NETWORK;
+    }
+    get isAuthenticationError() {
+        return this.type === ErrorType.AUTHENTICATION;
+    }
+    get isAuthorizationError() {
+        return this.type === ErrorType.AUTHORIZATION;
+    }
+    get isNotFoundError() {
+        return this.type === ErrorType.NOT_FOUND;
+    }
+    get isValidationError() {
+        return this.type === ErrorType.VALIDATION;
+    }
+    get isServerError() {
+        return this.type === ErrorType.SERVER;
+    }
+}

package/dist/core/event-emitter.d.ts

@@ -0,0 +1,11 @@
+import { SdkEventType, SdkEvents } from '../types/sdk';
+type Listener<T> = (data: T) => void;
+interface Subscription {
+    unsubscribe: () => void;
+}
+export declare class EventEmitter {
+    private listeners;
+    on<K extends SdkEventType>(event: K, listener: Listener<SdkEvents[K]>): Subscription;
+    emit<K extends SdkEventType>(event: K, data: SdkEvents[K]): void;
+}
+export {};

package/dist/core/event-emitter.js

@@ -0,0 +1,32 @@
+export class EventEmitter {
+    constructor() {
+        this.listeners = new Map();
+    }
+    // Suscribirse a un evento
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, []);
+        }
+        const eventListeners = this.listeners.get(event);
+        eventListeners.push(listener);
+        // Devolver objeto para cancelar suscripción
+        return {
+            unsubscribe: () => {
+                const index = eventListeners.indexOf(listener);
+                if (index !== -1) {
+                    eventListeners.splice(index, 1);
+                }
+            }
+        };
+    }
+    // Emitir un evento con datos
+    emit(event, data) {
+        if (!this.listeners.has(event)) {
+            return;
+        }
+        const eventListeners = this.listeners.get(event);
+        for (const listener of eventListeners) {
+            listener(data);
+        }
+    }
+}