@utilia-os/sdk-js 1.7.0 → 2.1.0

package/dist/index.mjs

@@ -171,6 +171,8 @@ var OAuthService = class {
   constructor(baseURL, config) {
     /** Estado PKCE en memoria como fallback cuando el storage no soporta pendingState */
     this._pendingState = null;
+    /** Promesa de refresco en curso para deduplicar llamadas concurrentes. */
+    this._refreshInFlight = null;
     this.baseURL = baseURL.replace(/\/$/, "");
     this.config = config;
     this.storage = config.tokenStorage ?? new MemoryTokenStorage();
@@ -186,7 +188,7 @@ var OAuthService = class {
    *
    * Este es el método recomendado para la mayoría de los casos.
    *
-   * @param options - Opciones adicionales (state personalizado, scopes)
+   * @param options - Opciones adicionales (state personalizado, scopes, parámetros OIDC)
    * @returns URL de autorización lista para redirigir al usuario
    */
   async getAuthorizationUrl(options) {
@@ -207,8 +209,8 @@ var OAuthService = class {
    * Método de control manual: devuelve codeVerifier y state que el desarrollador
    * debe gestionar. Para un flujo automático, usar getAuthorizationUrl() en su lugar.
    *
-   * @param options - Opciones adicionales (state personalizado, scopes)
-   * @returns URL de autorización, code_verifier y state
+   * Soporta los parámetros OIDC Core 1.0 §3.1.2.1: prompt, loginHint, nonce,
+   * maxAge y el Resource Indicator (RFC 8707) mediante el campo resource.
    */
   async getLoginUrl(options) {
     const codeVerifier = generateCodeVerifier();
@@ -224,6 +226,24 @@ var OAuthService = class {
       code_challenge: codeChallenge,
       code_challenge_method: "S256"
     });
+    if (options?.theme) {
+      params.set("theme", options.theme);
+    }
+    if (options?.prompt) {
+      params.set("prompt", options.prompt);
+    }
+    if (options?.loginHint) {
+      params.set("login_hint", options.loginHint);
+    }
+    if (options?.nonce) {
+      params.set("nonce", options.nonce);
+    }
+    if (options?.resource) {
+      params.set("resource", options.resource);
+    }
+    if (typeof options?.maxAge === "number" && Number.isFinite(options.maxAge) && options.maxAge >= 0) {
+      params.set("max_age", String(Math.floor(options.maxAge)));
+    }
     return {
       url: `${this.baseURL}/oauth/authorize?${params.toString()}`,
       codeVerifier,
@@ -243,7 +263,13 @@ var OAuthService = class {
     }
     const { url, codeVerifier, state } = await this.getLoginUrl({
       state: options?.state,
-      scopes: options?.scopes
+      scopes: options?.scopes,
+      theme: options?.theme,
+      prompt: options?.prompt,
+      loginHint: options?.loginHint,
+      nonce: options?.nonce,
+      resource: options?.resource,
+      maxAge: options?.maxAge
     });
     const width = options?.width ?? 500;
     const height = options?.height ?? 700;
@@ -361,37 +387,53 @@ var OAuthService = class {
     return tokens;
   }
   /**
-   * Refresca el token de acceso usando el refresh_token
+   * Refresca el token de acceso usando el refresh_token.
+   *
+   * Deduplica peticiones concurrentes mediante una promesa cacheada: si dos
+   * llamadas entran a la vez, comparten la misma petición HTTP. Esto es
+   * imprescindible porque el backend implementa rotación de refresh tokens con
+   * detección de reuso; dos refresh concurrentes con el mismo token producirían
+   * una invalidación inmediata de toda la cadena.
    *
    * @returns Nuevos tokens OAuth
    * @throws Error si no hay refresh_token disponible
    */
   async refreshToken() {
-    const current = await this.storage.getTokens();
-    if (!current?.refreshToken) {
-      throw new Error("No hay refresh token disponible. El usuario debe volver a autenticarse.");
-    }
-    const body = {
-      grant_type: "refresh_token",
-      refresh_token: current.refreshToken,
-      client_id: this.config.clientId
-    };
-    if (this.config.clientSecret) {
-      body.client_secret = this.config.clientSecret;
+    if (this._refreshInFlight) {
+      return this._refreshInFlight;
     }
-    const response = await this.http.post("/oauth/token", body);
-    const data = response.data;
-    const tokens = {
-      accessToken: data.access_token,
-      refreshToken: data.refresh_token ?? current.refreshToken,
-      expiresIn: data.expires_in,
-      expiresAt: Date.now() + data.expires_in * 1e3,
-      tokenType: data.token_type || "Bearer",
-      scope: data.scope,
-      idToken: data.id_token
-    };
-    await this.storage.setTokens(tokens);
-    return tokens;
+    this._refreshInFlight = (async () => {
+      try {
+        const current = await this.storage.getTokens();
+        if (!current?.refreshToken) {
+          throw new Error("No hay refresh token disponible. El usuario debe volver a autenticarse.");
+        }
+        const body = {
+          grant_type: "refresh_token",
+          refresh_token: current.refreshToken,
+          client_id: this.config.clientId
+        };
+        if (this.config.clientSecret) {
+          body.client_secret = this.config.clientSecret;
+        }
+        const response = await this.http.post("/oauth/token", body);
+        const data = response.data;
+        const tokens = {
+          accessToken: data.access_token,
+          refreshToken: data.refresh_token ?? current.refreshToken,
+          expiresIn: data.expires_in,
+          expiresAt: Date.now() + data.expires_in * 1e3,
+          tokenType: data.token_type || "Bearer",
+          scope: data.scope,
+          idToken: data.id_token
+        };
+        await this.storage.setTokens(tokens);
+        return tokens;
+      } finally {
+        this._refreshInFlight = null;
+      }
+    })();
+    return this._refreshInFlight;
   }
   /**
    * Obtiene información del usuario autenticado
@@ -406,9 +448,9 @@ var OAuthService = class {
     return response.data;
   }
   /**
-   * Revoca el token actual
+   * Revoca el token actual almacenado y limpia el storage.
    *
-   * @param tokenType - Tipo de token a revocar ('access_token' | 'refresh_token').
+   * @param tokenType - Tipo de token a revocar (`access_token` o `refresh_token`).
    *                     Por defecto revoca el access_token.
    */
   async revokeToken(tokenType) {
@@ -416,21 +458,76 @@ var OAuthService = class {
     if (!current) return;
     const token = tokenType === "refresh_token" ? current.refreshToken : current.accessToken;
     if (!token) return;
+    try {
+      await this.revoke(token, tokenType);
+    } catch {
+    }
+    await this.storage.clearTokens();
+  }
+  /**
+   * Revoca un token arbitrario contra el endpoint `/oauth/revoke` (RFC 7009).
+   * A diferencia de `revokeToken()`, no toca el almacenamiento local.
+   *
+   * @param token - Token a revocar (access token o refresh token).
+   * @param tokenTypeHint - Pista opcional sobre el tipo de token.
+   */
+  async revoke(token, tokenTypeHint) {
     const body = {
       token,
       client_id: this.config.clientId
     };
-    if (tokenType) {
-      body.token_type_hint = tokenType;
+    if (tokenTypeHint) {
+      body.token_type_hint = tokenTypeHint;
     }
     if (this.config.clientSecret) {
       body.client_secret = this.config.clientSecret;
     }
-    try {
-      await this.http.post("/oauth/revoke", body);
-    } catch {
+    await this.http.post("/oauth/revoke", body);
+  }
+  /**
+   * Introspecciona un token contra `/oauth/introspect` (RFC 7662).
+   * Requiere que el cliente esté autenticado (client_secret o public con PKCE).
+   *
+   * @param token - Token a introspeccionar.
+   * @param tokenTypeHint - Pista opcional sobre el tipo de token.
+   * @returns Estado y metadatos del token.
+   */
+  async introspect(token, tokenTypeHint) {
+    const body = {
+      token,
+      client_id: this.config.clientId
+    };
+    if (tokenTypeHint) {
+      body.token_type_hint = tokenTypeHint;
     }
-    await this.storage.clearTokens();
+    if (this.config.clientSecret) {
+      body.client_secret = this.config.clientSecret;
+    }
+    const response = await this.http.post("/oauth/introspect", body);
+    return response.data;
+  }
+  /**
+   * Lista las aplicaciones OAuth autorizadas por el usuario actual.
+   * Requiere un access token válido.
+   */
+  async getAuthorizedApps() {
+    const accessToken = await this.getAccessToken();
+    const response = await this.http.get("/oauth/apps", {
+      headers: { Authorization: `Bearer ${accessToken}` }
+    });
+    return response.data;
+  }
+  /**
+   * Revoca el acceso de una aplicación OAuth concreta del usuario actual.
+   * Todos los tokens emitidos para esa aplicación quedan invalidados.
+   */
+  async revokeApp(clientId) {
+    const accessToken = await this.getAccessToken();
+    await this.http.post(
+      `/oauth/apps/${encodeURIComponent(clientId)}/revoke`,
+      {},
+      { headers: { Authorization: `Bearer ${accessToken}` } }
+    );
   }
   /**
    * Obtiene un access token válido, refrescándolo automáticamente si ha expirado
@@ -1667,6 +1764,987 @@ var AiService = class {
   }
 };
 
+// src/services/budgets.service.ts
+var BudgetsService = class {
+  constructor(client) {
+    this.basePath = "/crm/budgets";
+    this.client = client;
+  }
+  // ==========================================
+  // Listado / detalle / CRUD
+  // ==========================================
+  /**
+   * Listar presupuestos aplicando filtros.
+   *
+   * @example
+   * ```typescript
+   * const page = await sdk.budgets.list({ status: 'SENT', page: 1, limit: 20 });
+   * console.log(page.data, page.pagination.total);
+   * ```
+   */
+  async list(filters) {
+    const params = this.serializeFilters(filters);
+    const raw = await this.client.get(this.basePath, {
+      params
+    });
+    return {
+      data: raw.data ?? raw.budgets ?? [],
+      pagination: raw.pagination
+    };
+  }
+  /** Obtener el detalle completo de un presupuesto por UUID. */
+  async get(id) {
+    validateRequired(id, "id");
+    return this.client.get(`${this.basePath}/${id}`);
+  }
+  /**
+   * Crear un nuevo presupuesto.
+   * Puede incluir items y secciones en la misma peticion.
+   */
+  async create(data) {
+    validateRequired(data.title, "title");
+    validateRequired(data.clientId, "clientId");
+    validateRequired(data.validUntil, "validUntil");
+    validateStringLength(data.title, "title", 1, 200);
+    return this.client.post(this.basePath, data);
+  }
+  /** Actualizar un presupuesto (solo en estado DRAFT salvo excepciones). */
+  async update(id, data) {
+    validateRequired(id, "id");
+    return this.client.patch(`${this.basePath}/${id}`, data);
+  }
+  /** Soft delete (puede recuperarse). */
+  async delete(id) {
+    validateRequired(id, "id");
+    return this.client.delete(`${this.basePath}/${id}`);
+  }
+  /**
+   * Eliminar de forma permanente.
+   * Solo disponible para SUPER_ADMIN en la organizacion origen.
+   */
+  async deletePermanent(id) {
+    validateRequired(id, "id");
+    return this.client.delete(
+      `${this.basePath}/${id}/permanent`
+    );
+  }
+  // ==========================================
+  // Duplicado / versiones / historial
+  // ==========================================
+  /** Duplicar un presupuesto sin encadenarlo como nueva version. */
+  async duplicate(id, options) {
+    validateRequired(id, "id");
+    return this.client.post(
+      `${this.basePath}/${id}/duplicate`,
+      options ?? {}
+    );
+  }
+  /** Crear una nueva version DRAFT del presupuesto, incrementando el contador. */
+  async createVersion(id) {
+    validateRequired(id, "id");
+    return this.client.post(`${this.basePath}/${id}/new-version`);
+  }
+  /** Historial de versiones y cambios. */
+  async getHistory(id) {
+    validateRequired(id, "id");
+    return this.client.get(
+      `${this.basePath}/${id}/history`
+    );
+  }
+  // ==========================================
+  // Listado por entidad relacionada
+  // ==========================================
+  /** Presupuestos de un cliente. */
+  async listByClient(clientId) {
+    validateRequired(clientId, "clientId");
+    return this.client.get(
+      `${this.basePath}/by-entity/client/${clientId}`
+    );
+  }
+  /** Presupuestos de un proyecto. */
+  async listByProject(projectId) {
+    validateRequired(projectId, "projectId");
+    return this.client.get(
+      `${this.basePath}/by-entity/project/${projectId}`
+    );
+  }
+  /** Presupuestos de una oportunidad. */
+  async listByOpportunity(opportunityId) {
+    validateRequired(opportunityId, "opportunityId");
+    return this.client.get(
+      `${this.basePath}/by-entity/opportunity/${opportunityId}`
+    );
+  }
+  // ==========================================
+  // Items
+  // ==========================================
+  /** Anyadir un item al presupuesto. */
+  async addItem(budgetId, data) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(data.name, "name");
+    return this.client.post(
+      `${this.basePath}/${budgetId}/items`,
+      data
+    );
+  }
+  /** Actualizar un item. */
+  async updateItem(budgetId, itemId, data) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(itemId, "itemId");
+    return this.client.patch(
+      `${this.basePath}/${budgetId}/items/${itemId}`,
+      data
+    );
+  }
+  /** Eliminar un item. */
+  async removeItem(budgetId, itemId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(itemId, "itemId");
+    return this.client.delete(
+      `${this.basePath}/${budgetId}/items/${itemId}`
+    );
+  }
+  /** Aplicar un nuevo orden a los items del presupuesto. */
+  async reorderItems(budgetId, data) {
+    validateRequired(budgetId, "budgetId");
+    return this.client.patch(
+      `${this.basePath}/${budgetId}/items/reorder`,
+      data
+    );
+  }
+  // ==========================================
+  // Secciones
+  // ==========================================
+  /** Listar secciones del presupuesto ordenadas por posicion y orden. */
+  async listSections(budgetId) {
+    validateRequired(budgetId, "budgetId");
+    return this.client.get(
+      `${this.basePath}/${budgetId}/sections`
+    );
+  }
+  /** Anyadir una seccion al presupuesto. */
+  async addSection(budgetId, data) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(data.title, "title");
+    return this.client.post(
+      `${this.basePath}/${budgetId}/sections`,
+      data
+    );
+  }
+  /** Actualizar una seccion existente. */
+  async updateSection(budgetId, sectionId, data) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(sectionId, "sectionId");
+    return this.client.patch(
+      `${this.basePath}/${budgetId}/sections/${sectionId}`,
+      data
+    );
+  }
+  /** Eliminar una seccion. */
+  async removeSection(budgetId, sectionId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(sectionId, "sectionId");
+    return this.client.delete(
+      `${this.basePath}/${budgetId}/sections/${sectionId}`
+    );
+  }
+  /** Reordenar secciones. */
+  async reorderSections(budgetId, data) {
+    validateRequired(budgetId, "budgetId");
+    return this.client.patch(
+      `${this.basePath}/${budgetId}/sections/reorder`,
+      data
+    );
+  }
+  // ==========================================
+  // Acciones de flujo
+  // ==========================================
+  /** Enviar el presupuesto por correo al cliente. */
+  async send(id, data) {
+    validateRequired(id, "id");
+    if (!Array.isArray(data.emails) || data.emails.length === 0) {
+      throw new Error("Debes indicar al menos un email destinatario");
+    }
+    return this.client.post(`${this.basePath}/${id}/send`, data);
+  }
+  /** Aprobar el presupuesto. */
+  async approve(id, data = {}) {
+    validateRequired(id, "id");
+    return this.client.post(`${this.basePath}/${id}/approve`, data);
+  }
+  /** Rechazar el presupuesto. El motivo (reason) es obligatorio. */
+  async reject(id, data) {
+    validateRequired(id, "id");
+    validateRequired(data.reason, "reason");
+    return this.client.post(`${this.basePath}/${id}/reject`, data);
+  }
+  /** Cancelar el presupuesto. */
+  async cancel(id) {
+    validateRequired(id, "id");
+    return this.client.post(`${this.basePath}/${id}/cancel`);
+  }
+  /**
+   * Cambiar el estado del presupuesto directamente (uso administrativo).
+   * Restringido a SUPER_ADMIN en el backend.
+   */
+  async changeStatus(id, status, reason) {
+    validateRequired(id, "id");
+    validateRequired(status, "status");
+    const payload = { status, reason };
+    return this.client.post(
+      `${this.basePath}/${id}/change-status`,
+      payload
+    );
+  }
+  /** Convertir un presupuesto aprobado en un proyecto CRM. */
+  async convertToProject(id, options) {
+    validateRequired(id, "id");
+    validateRequired(options.name, "name");
+    validateRequired(options.startDate, "startDate");
+    return this.client.post(
+      `${this.basePath}/${id}/convert-to-project`,
+      options
+    );
+  }
+  /** Convertir un presupuesto aprobado en factura. */
+  async convertToInvoice(id, options = {}) {
+    validateRequired(id, "id");
+    return this.client.post(
+      `${this.basePath}/${id}/convert-to-invoice`,
+      options
+    );
+  }
+  // ==========================================
+  // PDF
+  // ==========================================
+  /**
+   * Generar el PDF del presupuesto para descarga.
+   * Devuelve un Blob. Si el consumidor necesita una URL, usa `URL.createObjectURL`.
+   */
+  async generatePdf(id) {
+    validateRequired(id, "id");
+    return this.fetchBinary(`${this.basePath}/${id}/generate-pdf`, "POST");
+  }
+  /**
+   * Visualizar el PDF del presupuesto (Content-Disposition inline).
+   * Devuelve un Blob.
+   */
+  async viewPdf(id) {
+    validateRequired(id, "id");
+    return this.fetchBinary(`${this.basePath}/${id}/pdf`, "GET");
+  }
+  /**
+   * Construir la URL del PDF del presupuesto (util para <iframe>, <embed>, etc.).
+   * Incluye las credenciales en query string para funcionar en etiquetas HTML
+   * que no pueden anyadir headers personalizados.
+   */
+  getPdfUrl(id) {
+    validateRequired(id, "id");
+    return this.client.buildSseUrl(`${this.basePath}/${id}/pdf`);
+  }
+  // ==========================================
+  // Adjuntos
+  // ==========================================
+  /** Listar adjuntos del presupuesto. */
+  async getAttachments(budgetId) {
+    validateRequired(budgetId, "budgetId");
+    return this.client.get(
+      `${this.basePath}/${budgetId}/attachments`
+    );
+  }
+  /**
+   * Subir un adjunto al presupuesto.
+   *
+   * @param budgetId - UUID del presupuesto
+   * @param file - Archivo a subir (File o Blob)
+   * @param meta - Nombre visible y descripcion opcionales
+   */
+  async uploadAttachment(budgetId, file, meta) {
+    validateRequired(budgetId, "budgetId");
+    const formData = new FormData();
+    if (file instanceof Blob && !(file instanceof File)) {
+      formData.append("file", file, meta?.name || "attachment");
+    } else {
+      formData.append("file", file);
+    }
+    if (meta?.name) formData.append("name", meta.name);
+    if (meta?.description) formData.append("description", meta.description);
+    return this.client.postForm(
+      `${this.basePath}/${budgetId}/attachments`,
+      formData
+    );
+  }
+  /** Eliminar un adjunto del presupuesto. */
+  async deleteAttachment(budgetId, attachmentId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(attachmentId, "attachmentId");
+    return this.client.delete(
+      `${this.basePath}/${budgetId}/attachments/${attachmentId}`
+    );
+  }
+  /**
+   * Subir una imagen para el editor WYSIWYG.
+   * La imagen no aparece como adjunto en el File Manager: solo devuelve la URL
+   * para incrustarla en el contenido del presupuesto.
+   */
+  async uploadEditorImage(budgetId, file) {
+    validateRequired(budgetId, "budgetId");
+    const formData = new FormData();
+    if (file instanceof Blob && !(file instanceof File)) {
+      formData.append("file", file, "image");
+    } else {
+      formData.append("file", file);
+    }
+    return this.client.postForm(
+      `${this.basePath}/${budgetId}/editor-images`,
+      formData
+    );
+  }
+  // ==========================================
+  // Utilidades: codigo, stats, export, masivos
+  // ==========================================
+  /** Proximo codigo sugerido segun la configuracion de numeracion. */
+  async getNextCode() {
+    return this.client.get(`${this.basePath}/next-code`);
+  }
+  /** Comprobar si un codigo ya esta en uso. */
+  async checkCode(code, excludeId) {
+    validateRequired(code, "code");
+    return this.client.get(
+      `${this.basePath}/check-code/${encodeURIComponent(code)}`,
+      { params: excludeId ? { excludeId } : void 0 }
+    );
+  }
+  /** Estadisticas agregadas (totales, tasa aprobacion, etc.). */
+  async getStats(filters) {
+    const params = this.serializeFilters(filters);
+    return this.client.get(`${this.basePath}/stats`, {
+      params
+    });
+  }
+  /** Ejecutar una operacion masiva (delete / cancel / change-status). */
+  async bulk(operation, ids, options) {
+    if (!Array.isArray(ids) || ids.length === 0) {
+      throw new Error("Debes indicar al menos un id de presupuesto");
+    }
+    const payload = { operation, ids, options };
+    return this.client.post(`${this.basePath}/bulk`, payload);
+  }
+  /**
+   * Exportar el listado filtrado en el formato indicado.
+   * De momento solo se soporta `csv`. Devuelve un Blob.
+   */
+  async export(filters, format = "csv") {
+    if (format !== "csv") {
+      throw new Error(`Formato de exportacion no soportado: ${format}`);
+    }
+    const params = this.serializeFilters(filters);
+    return this.fetchBinary(`${this.basePath}/export`, "GET", params);
+  }
+  // ==========================================
+  // IA
+  // ==========================================
+  /**
+   * Encolar un job asincrono para generar items del presupuesto a partir
+   * de un texto en lenguaje natural. Devuelve el `jobId` para seguir el
+   * progreso vía `streamGenerateItemsStatus`.
+   */
+  async generateItemsWithAi(data) {
+    validateRequired(data.text, "text");
+    validateStringLength(data.text, "text", 10);
+    return this.client.post(
+      `${this.basePath}/generate-items-ai`,
+      data
+    );
+  }
+  /**
+   * Suscribirse al progreso (SSE) del job de generacion de items con IA.
+   * Requiere EventSource en el entorno.
+   */
+  streamGenerateItemsStatus(jobId, options) {
+    validateRequired(jobId, "jobId");
+    if (typeof EventSource === "undefined") {
+      throw new Error(
+        "EventSource no esta disponible en este entorno. Usa un polyfill en Node."
+      );
+    }
+    const sseUrl = this.client.buildSseUrl(
+      `${this.basePath}/generate-items-ai/${jobId}/status`
+    );
+    const es = new EventSource(sseUrl);
+    es.addEventListener("progress", (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        options?.onProgress?.(data);
+      } catch {
+      }
+    });
+    es.addEventListener("complete", (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        options?.onComplete?.(data);
+      } catch {
+      } finally {
+        es.close();
+      }
+    });
+    es.addEventListener("error", (event) => {
+      try {
+        const data = event.data ? JSON.parse(event.data) : null;
+        options?.onError?.(
+          new Error(data?.error || "Error en el job de generacion de items")
+        );
+      } catch {
+        options?.onError?.(new Error("Error en la conexion SSE"));
+      } finally {
+        es.close();
+      }
+    });
+    return { close: () => es.close() };
+  }
+  /**
+   * Generar un presupuesto completo (secciones + items) a partir de un texto.
+   * Devuelve la estructura sugerida sin crear el presupuesto.
+   */
+  async generateCompleteWithAi(data) {
+    validateRequired(data.text, "text");
+    validateStringLength(data.text, "text", 10);
+    return this.client.post(
+      `${this.basePath}/generate-complete-ai`,
+      data
+    );
+  }
+  /** Generar unicamente secciones sugeridas para un presupuesto existente. */
+  async generateSectionsWithAi(data) {
+    validateRequired(data.text, "text");
+    validateStringLength(data.text, "text", 10);
+    return this.client.post(
+      `${this.basePath}/generate-sections-ai`,
+      data
+    );
+  }
+  // ==========================================
+  // Helpers privados
+  // ==========================================
+  /**
+   * Convierte los filtros a un objeto plano apto para query string.
+   * Aplana arrays en formato coma-separado (patron del backend).
+   */
+  serializeFilters(filters) {
+    if (!filters) return void 0;
+    const out = {};
+    for (const [key, value] of Object.entries(filters)) {
+      if (value === void 0 || value === null) continue;
+      if (Array.isArray(value)) {
+        out[key] = value.join(",");
+      } else {
+        out[key] = value;
+      }
+    }
+    return out;
+  }
+  /**
+   * Descargar una respuesta binaria (PDF, CSV) respetando el auth del cliente.
+   * Usa `buildSseUrl` para añadir las credenciales en la URL cuando la ruta
+   * no pueda llevarlas en headers (p. ej. etiquetas `<a href>`).
+   */
+  async fetchBinary(path, method, params) {
+    if (method === "GET") {
+      const response2 = await this.client.get(path, {
+        params,
+        responseType: "arraybuffer"
+      });
+      return new Blob([response2]);
+    }
+    const response = await this.client.post(path, void 0, {
+      params,
+      responseType: "arraybuffer"
+    });
+    return new Blob([response]);
+  }
+};
+
+// src/services/budget-templates.service.ts
+var BudgetTemplatesService = class {
+  constructor(client) {
+    this.basePath = "/crm/budget-templates";
+    this.budgetsPath = "/crm/budgets";
+    this.client = client;
+  }
+  /**
+   * Listar plantillas activas.
+   * Las plantillas del sistema aparecen primero, seguidas de las
+   * personalizadas ordenadas por fecha de creacion descendente.
+   */
+  async list() {
+    return this.client.get(this.basePath);
+  }
+  /** Obtener el detalle de una plantilla por UUID. */
+  async get(id) {
+    validateRequired(id, "id");
+    return this.client.get(`${this.basePath}/${id}`);
+  }
+  /** Crear una plantilla personalizada. */
+  async create(data) {
+    validateRequired(data.name, "name");
+    validateStringLength(data.name, "name", 1, 100);
+    return this.client.post(this.basePath, data);
+  }
+  /** Actualizar una plantilla personalizada (las del sistema son inmutables). */
+  async update(id, data) {
+    validateRequired(id, "id");
+    return this.client.patch(`${this.basePath}/${id}`, data);
+  }
+  /** Archivar (soft delete) una plantilla personalizada. */
+  async delete(id) {
+    validateRequired(id, "id");
+    return this.client.delete(`${this.basePath}/${id}`);
+  }
+  /**
+   * Crear una plantilla personalizada copiando items y secciones de un
+   * presupuesto existente.
+   */
+  async createFromBudget(budgetId, data) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(data.name, "name");
+    return this.client.post(
+      `${this.basePath}/from-budget/${budgetId}`,
+      data
+    );
+  }
+  /**
+   * Crear un presupuesto DRAFT aplicando una plantilla.
+   * Copia los items/secciones de la plantilla y asigna cliente/oportunidad.
+   */
+  async applyTemplate(templateId, data) {
+    validateRequired(templateId, "templateId");
+    validateRequired(data.clientId, "clientId");
+    return this.client.post(
+      `${this.budgetsPath}/from-template/${templateId}`,
+      data
+    );
+  }
+};
+
+// src/services/budget-comments.service.ts
+var BudgetCommentsService = class {
+  constructor(client) {
+    this.basePath = "/crm/budgets";
+    this.client = client;
+  }
+  /**
+   * Listar comentarios del presupuesto.
+   *
+   * @param budgetId - UUID del presupuesto.
+   * @param filter - Filtros de visibilidad, paginación y rango de fechas.
+   *
+   * @example
+   * ```typescript
+   * const page = await sdk.budgetComments.list(budgetId, { visibility: 'CLIENT', page: 1, limit: 20 });
+   * page.data.forEach(c => console.log(c.body));
+   * ```
+   */
+  async list(budgetId, filter) {
+    validateRequired(budgetId, "budgetId");
+    const params = this.serializeListFilter(filter);
+    const raw = await this.client.get(
+      `${this.basePath}/${budgetId}/comments`,
+      { params }
+    );
+    const data = raw.data ?? raw.items ?? [];
+    const pageInfo = {
+      ...raw.pagination ?? {},
+      ...raw.pageInfo ?? {}
+    };
+    return { data, pageInfo };
+  }
+  /**
+   * Obtener un comentario por su ID.
+   *
+   * Nota: el backend actual no expone `GET /comments/:commentId` a nivel de
+   * REST. El SDK lo emula filtrando localmente el resultado del listado. Si
+   * en el futuro se añade un endpoint dedicado, este método se puede migrar
+   * sin romper la firma.
+   */
+  async get(budgetId, commentId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(commentId, "commentId");
+    const page = await this.list(budgetId, { limit: 100 });
+    const found = page.data.find((c) => c.id === commentId);
+    if (!found) {
+      throw new Error(
+        `Comentario ${commentId} no encontrado en el presupuesto ${budgetId}`
+      );
+    }
+    return found;
+  }
+  /**
+   * Crear un comentario en el presupuesto.
+   *
+   * La visibilidad (INTERNAL / CLIENT) debe ser compatible con los permisos
+   * del usuario autenticado. Las menciones solo tienen efecto en comentarios
+   * internos.
+   */
+  async create(budgetId, input) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(input.body, "body");
+    validateStringLength(input.body, "body", 1, 5e3);
+    return this.client.post(
+      `${this.basePath}/${budgetId}/comments`,
+      input
+    );
+  }
+  /** Actualizar el cuerpo de un comentario. Solo autor o SUPER_ADMIN. */
+  async update(budgetId, commentId, input) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(commentId, "commentId");
+    validateRequired(input.body, "body");
+    validateStringLength(input.body, "body", 1, 5e3);
+    return this.client.patch(
+      `${this.basePath}/${budgetId}/comments/${commentId}`,
+      input
+    );
+  }
+  /** Eliminar un comentario. Solo autor o SUPER_ADMIN. */
+  async remove(budgetId, commentId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(commentId, "commentId");
+    return this.client.delete(
+      `${this.basePath}/${budgetId}/comments/${commentId}`
+    );
+  }
+  /**
+   * Creación masiva tolerante a fallos (saga).
+   *
+   * Nota: a día de hoy, el backend expone el bulk únicamente a través de la
+   * herramienta MCP `crm_budget_comments.bulk_create`. Para consumirlo desde
+   * REST, el SDK llama secuencialmente a `create` y agrega el resultado,
+   * respetando el contrato del método. Sustituir cuando exista un endpoint
+   * REST dedicado.
+   */
+  async bulkCreate(budgetId, items, options) {
+    validateRequired(budgetId, "budgetId");
+    if (!Array.isArray(items) || items.length === 0) {
+      throw new Error("Debes indicar al menos un comentario en items");
+    }
+    if (items.length > 50) {
+      throw new Error("No se pueden crear m\xE1s de 50 comentarios por lote");
+    }
+    if (options?.idempotencyKey) {
+      try {
+        const raw = await this.client.post(
+          `${this.basePath}/${budgetId}/comments:bulk`,
+          { items },
+          { headers: { "Idempotency-Key": options.idempotencyKey } }
+        );
+        return this.normalizeBulkResult(raw);
+      } catch {
+      }
+    }
+    const succeeded = [];
+    const failed = [];
+    for (let index = 0; index < items.length; index += 1) {
+      const dto = items[index];
+      try {
+        const created = await this.create(budgetId, dto);
+        succeeded.push(created);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Error desconocido";
+        failed.push({
+          index,
+          clientOperationId: dto.clientOperationId,
+          code: this.mapErrorCode(error),
+          message
+        });
+      }
+    }
+    return {
+      succeeded,
+      failed,
+      summary: {
+        total: items.length,
+        ok: succeeded.length,
+        failed: failed.length
+      }
+    };
+  }
+  /**
+   * Devuelve el timeline unificado: comentarios + eventos de historial del
+   * presupuesto ordenados cronológicamente descendente.
+   *
+   * Nota: el backend expone esta vista agregada a través de la herramienta MCP
+   * `crm_budget_comments.get_timeline`. Hasta que se habilite un endpoint REST
+   * dedicado, el SDK devuelve los comentarios paginados y un `items` sólo con
+   * kind `COMMENT`. Se marca como follow-up.
+   */
+  async getTimeline(budgetId, filter) {
+    validateRequired(budgetId, "budgetId");
+    try {
+      const params = this.serializeTimelineFilter(filter);
+      const raw = await this.client.get(
+        `${this.basePath}/${budgetId}/timeline`,
+        { params }
+      );
+      return raw;
+    } catch {
+      const page = await this.list(budgetId, {
+        limit: filter?.limit ?? 50,
+        since: filter?.since,
+        until: filter?.until
+      });
+      return {
+        items: page.data.map((comment) => ({
+          kind: "COMMENT",
+          at: comment.createdAt,
+          comment
+        })),
+        pageInfo: {
+          nextCursor: page.pageInfo?.nextCursor ?? null,
+          hasMore: page.pageInfo?.hasMore ?? false,
+          pageSize: page.data.length
+        }
+      };
+    }
+  }
+  // ==========================================
+  // Helpers privados
+  // ==========================================
+  serializeListFilter(filter) {
+    if (!filter) return void 0;
+    const out = {};
+    if (filter.visibility && filter.visibility !== "ALL") {
+      out.visibility = filter.visibility;
+    }
+    if (filter.authorId) out.authorId = filter.authorId;
+    if (filter.mentionedUserId) out.mentionedUserId = filter.mentionedUserId;
+    if (filter.cursor) out.cursor = filter.cursor;
+    if (typeof filter.limit === "number") out.limit = filter.limit;
+    if (typeof filter.page === "number") out.page = filter.page;
+    if (filter.since) out.since = filter.since;
+    if (filter.until) out.until = filter.until;
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+  serializeTimelineFilter(filter) {
+    if (!filter) return void 0;
+    const out = {};
+    if (filter.cursor) out.cursor = filter.cursor;
+    if (typeof filter.limit === "number") out.limit = filter.limit;
+    if (filter.since) out.since = filter.since;
+    if (filter.until) out.until = filter.until;
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+  normalizeBulkResult(raw) {
+    const total = raw.summary?.total ?? raw.succeeded.length + raw.failed.length;
+    const ok = raw.summary?.ok ?? raw.succeeded.length;
+    const failed = raw.summary?.failed ?? raw.failed.length;
+    return {
+      succeeded: raw.succeeded,
+      failed: raw.failed,
+      summary: { total, ok, failed }
+    };
+  }
+  mapErrorCode(error) {
+    if (!error || typeof error !== "object") return "INTERNAL";
+    const code = error.code;
+    if (typeof code === "string") return code;
+    const statusCode = error.statusCode;
+    if (statusCode === 404) return "NOT_FOUND";
+    if (statusCode === 403) return "FORBIDDEN";
+    if (statusCode === 400) return "VALIDATION";
+    if (statusCode === 409) return "CONFLICT";
+    if (statusCode === 429) return "RATE_LIMITED";
+    return "INTERNAL";
+  }
+};
+
+// src/services/budget-signatures.service.ts
+var BudgetSignaturesService = class {
+  constructor(client) {
+    this.basePath = "/crm/budgets";
+    this.client = client;
+  }
+  // ==========================================
+  // Firmas registradas
+  // ==========================================
+  /** Listar todas las firmas asociadas al presupuesto. */
+  async list(budgetId) {
+    validateRequired(budgetId, "budgetId");
+    const raw = await this.client.get(
+      `${this.basePath}/${budgetId}/signatures`
+    );
+    return raw.items ?? [];
+  }
+  /** Obtener el detalle de una firma concreta. */
+  async get(budgetId, signatureId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(signatureId, "signatureId");
+    return this.client.get(
+      `${this.basePath}/${budgetId}/signatures/${signatureId}`
+    );
+  }
+  /**
+   * Verificar la integridad de una firma. Recalcula el hash del documento con
+   * la versión (`hashVersion`) con la que se firmó originalmente y lo compara.
+   *
+   * Si `valid === false`, el documento ha sido modificado después de firmar.
+   */
+  async verify(budgetId, signatureId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(signatureId, "signatureId");
+    return this.client.get(
+      `${this.basePath}/${budgetId}/signatures/${signatureId}/verify`
+    );
+  }
+  /**
+   * Descargar el certificado legal de una firma como Blob.
+   *
+   * Ideal para consumidores que necesiten guardar el PDF localmente o abrirlo
+   * con `URL.createObjectURL`.
+   */
+  async downloadCertificate(budgetId, signatureId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(signatureId, "signatureId");
+    const response = await this.client.get(
+      `${this.basePath}/${budgetId}/signatures/${signatureId}/certificate.pdf`,
+      { responseType: "arraybuffer" }
+    );
+    return new Blob([response], { type: "application/pdf" });
+  }
+  /**
+   * Construir la URL del certificado (útil para `<iframe>` o enlaces directos).
+   * Incluye las credenciales en query string cuando el SDK usa API key.
+   */
+  getCertificateUrl(budgetId, signatureId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(signatureId, "signatureId");
+    return this.client.buildSseUrl(
+      `${this.basePath}/${budgetId}/signatures/${signatureId}/certificate.pdf`
+    );
+  }
+  // ==========================================
+  // Magic links
+  // ==========================================
+  /**
+   * Generar un magic link de firma. El endpoint es idempotente para la tupla
+   * (budgetId, signerEmail): si ya existe un token vivo se devuelve con
+   * `reused: true` y `signingUrl: null` (el raw token original no se
+   * recupera).
+   */
+  async generateSigningLink(budgetId, input) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(input.signerEmail, "signerEmail");
+    return this.client.post(
+      `${this.basePath}/${budgetId}/signing-link`,
+      input
+    );
+  }
+  /**
+   * Listar los magic links vivos del presupuesto (no usados, no revocados y no
+   * expirados). Los filtros `includeRevoked`/`includeExpired` se reservan para
+   * cuando el backend exponga la vista extendida.
+   */
+  async listSigningLinks(budgetId, filter) {
+    validateRequired(budgetId, "budgetId");
+    const params = this.serializeSigningLinksFilter(filter);
+    const raw = await this.client.get(
+      `${this.basePath}/${budgetId}/signing-links`,
+      { params }
+    );
+    return raw.items ?? [];
+  }
+  /** Revocar un magic link. Idempotente: llamarla dos veces no falla. */
+  async revokeSigningLink(budgetId, tokenId) {
+    validateRequired(budgetId, "budgetId");
+    validateRequired(tokenId, "tokenId");
+    return this.client.delete(
+      `${this.basePath}/${budgetId}/signing-links/${tokenId}`
+    );
+  }
+  /**
+   * Audit trail paginado por cursor de los eventos de firma del presupuesto
+   * (emisión, visualización, descarga de PDF, aprobación, rechazo,
+   * expiración, revocación, fallos).
+   */
+  async getAuditTrail(budgetId, filter) {
+    validateRequired(budgetId, "budgetId");
+    const params = this.serializeAuditFilter(filter);
+    const raw = await this.client.get(
+      `${this.basePath}/${budgetId}/signing-links/audit`,
+      { params }
+    );
+    const items = raw.items ?? [];
+    if (filter?.tokenId) {
+      return items.filter((e) => e.tokenId === filter.tokenId);
+    }
+    return items;
+  }
+  // ==========================================
+  // Helpers privados
+  // ==========================================
+  serializeSigningLinksFilter(filter) {
+    if (!filter) return void 0;
+    const out = {};
+    if (typeof filter.includeRevoked === "boolean") {
+      out.includeRevoked = filter.includeRevoked;
+    }
+    if (typeof filter.includeExpired === "boolean") {
+      out.includeExpired = filter.includeExpired;
+    }
+    if (filter.cursor) out.cursor = filter.cursor;
+    if (typeof filter.limit === "number") out.limit = filter.limit;
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+  serializeAuditFilter(filter) {
+    if (!filter) return void 0;
+    const out = {};
+    if (filter.cursor) out.cursor = filter.cursor;
+    if (typeof filter.limit === "number") out.limit = filter.limit;
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+};
+
+// src/services/organization-settings.service.ts
+var OrganizationSettingsService = class {
+  constructor(client) {
+    this.basePath = "/organization-settings";
+    this.client = client;
+  }
+  /**
+   * Obtener los datos públicos de la organización.
+   *
+   * Incluye identidad corporativa, branding, configuración de facturación
+   * (moneda, impuesto por defecto, país) y canales de contacto.
+   *
+   * @returns Configuración pública de la organización.
+   *
+   * @example
+   * ```typescript
+   * const settings = await sdk.organizationSettings.getPublicSettings();
+   * console.log(settings.defaultCurrency); // "EUR"
+   * console.log(settings.defaultTaxName);  // "IVA"
+   * console.log(settings.defaultTaxRate);  // 21
+   * console.log(settings.country);         // "ES"
+   * ```
+   */
+  async getPublicSettings() {
+    return this.client.get(`${this.basePath}/public`);
+  }
+};
+
+// src/types/budget.types.ts
+var BUDGET_WEBHOOK_EVENTS = [
+  "BUDGET_CREATED",
+  "BUDGET_UPDATED",
+  "BUDGET_SENT",
+  "BUDGET_APPROVED",
+  "BUDGET_REJECTED",
+  "BUDGET_CANCELLED",
+  "BUDGET_EXPIRED",
+  "BUDGET_DUPLICATED",
+  "BUDGET_CONVERTED_TO_PROJECT",
+  "BUDGET_CONVERTED_TO_INVOICE"
+];
+
 // src/index.ts
 var UtiliaSDK = class {
   /**
@@ -1706,6 +2784,11 @@ var UtiliaSDK = class {
     this.tickets = new TicketsService(this._client);
     this.users = new UsersService(this._client);
     this.ai = new AiService(this._client);
+    this.budgets = new BudgetsService(this._client);
+    this.budgetTemplates = new BudgetTemplatesService(this._client);
+    this.budgetComments = new BudgetCommentsService(this._client);
+    this.budgetSignatures = new BudgetSignaturesService(this._client);
+    this.organizationSettings = new OrganizationSettingsService(this._client);
   }
   /**
    * Servicio OAuth (solo disponible si se configuro oauth en el constructor)
@@ -1715,6 +2798,7 @@ var UtiliaSDK = class {
   }
 };
 export {
+  BUDGET_WEBHOOK_EVENTS,
   ErrorCode,
   FileTokenStorage,
   MemoryTokenStorage,