@utilia-os/sdk-js 1.1.0 → 1.2.0

package/dist/index.d.mts

@@ -43,10 +43,22 @@ declare class UtiliaClient {
      * Ejecuta una funcion con reintentos y backoff exponencial
      */
     private executeWithRetry;
+    /**
+     * Genera un ID simple como fallback cuando crypto.randomUUID no esta disponible
+     */
+    private generateSimpleId;
     /**
      * Helper para esperar un tiempo
      */
     private sleep;
+    /**
+     * Construye una URL completa para conexiones SSE con la API key como query param.
+     * Util para EventSource que no soporta headers personalizados.
+     *
+     * @param path - Ruta relativa de la API (ej: /external/v1/tickets/ai-suggest/123/stream)
+     * @returns URL completa con apiKey como parametro de consulta
+     */
+    buildSseUrl(path: string): string;
     /**
      * Realiza una peticion GET
      */
@@ -672,6 +684,65 @@ interface GetSuggestionsOptions {
     /** Callback para reportar progreso */
     onProgress?: (progress: number) => void;
 }
+/**
+ * Evento SSE recibido durante el streaming de un job
+ */
+interface SseEvent {
+    /** Tipo de evento */
+    event: 'progress' | 'completed' | 'failed' | 'heartbeat';
+    /** Progreso actual (0-100) */
+    progress?: number;
+    /** Estado descriptivo */
+    status?: string;
+    /** Resultado del job (disponible en evento 'completed') */
+    result?: AiJobStatus['result'];
+    /** Mensaje de error (disponible en evento 'failed') */
+    error?: string;
+}
+/**
+ * Opciones para el metodo streamSuggestions
+ */
+interface StreamSuggestionsOptions {
+    /** Callback para reportar progreso (0-100) */
+    onProgress?: (progress: number) => void;
+    /** Callback para errores no fatales */
+    onError?: (error: Error) => void;
+    /** Timeout en ms (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Handle retornado por streamSuggestions para controlar la conexion SSE
+ */
+interface StreamSuggestionsHandle {
+    /** Promesa que resuelve con el resultado cuando el job completa */
+    result: Promise<AiJobStatus['result']>;
+    /** Funcion para abortar la conexion SSE */
+    abort: () => void;
+}
+/**
+ * Estado del job de transcripcion asincrona
+ */
+interface TranscriptionJobStatus {
+    /** Estado actual del job */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Progreso del job (0-100) */
+    progress?: number;
+    /** Texto transcrito (disponible cuando status es 'completed') */
+    transcription?: string;
+    /** Mensaje de error (si status es 'failed') */
+    error?: string;
+}
+/**
+ * Opciones para el metodo streamTranscription
+ */
+interface StreamTranscriptionOptions {
+    /** Callback para reportar progreso (0-100) */
+    onProgress?: (progress: number) => void;
+    /** Callback para errores no fatales */
+    onError?: (error: Error) => void;
+    /** Timeout en ms (default: 120000) */
+    timeout?: number;
+}
 declare class AiService {
     private readonly client;
     private readonly basePath;
@@ -794,6 +865,122 @@ declare class AiService {
     trackAiAction(data: TrackAiActionInput): Promise<{
         success: boolean;
     }>;
+    /**
+     * Solicita sugerencias de IA y recibe el resultado via SSE (Server-Sent Events).
+     * Alternativa al polling que ofrece actualizaciones en tiempo real.
+     *
+     * Requiere un entorno con EventSource nativo (navegador).
+     * Para Node.js se necesita un polyfill como 'eventsource'.
+     *
+     * @param data - Datos para generar sugerencias
+     * @param options - Opciones de streaming
+     * @returns Handle con promesa de resultado y funcion de aborto
+     *
+     * @example
+     * ```typescript
+     * const handle = await sdk.ai.streamSuggestions(
+     *   { userId: 'user-123', text: 'No puedo iniciar sesion' },
+     *   { onProgress: (p) => console.log(`Progreso: ${p}%`) },
+     * );
+     *
+     * // Esperar resultado
+     * const result = await handle.result;
+     * console.log(result?.suggestions);
+     *
+     * // O abortar si el usuario cancela
+     * handle.abort();
+     * ```
+     */
+    streamSuggestions(data: AiSuggestInput, options?: StreamSuggestionsOptions): Promise<StreamSuggestionsHandle>;
+    /**
+     * Solicita una transcripcion de audio de forma asincrona.
+     * Retorna un jobId para consultar el estado o usar con streamTranscription.
+     *
+     * @param audioBase64 - Audio codificado en base64
+     * @param audioFilename - Nombre del archivo con extension
+     * @returns ID del job para consultar estado
+     *
+     * @example
+     * ```typescript
+     * const { jobId } = await sdk.ai.requestTranscription(
+     *   audioBase64,
+     *   'recording.webm',
+     * );
+     * ```
+     */
+    requestTranscription(audioBase64: string, audioFilename: string): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Obtiene el estado de un job de transcripcion asincrona.
+     *
+     * @param jobId - ID del job obtenido de requestTranscription
+     * @returns Estado actual del job de transcripcion
+     *
+     * @example
+     * ```typescript
+     * const status = await sdk.ai.getTranscriptionStatus(jobId);
+     *
+     * if (status.status === 'completed') {
+     *   console.log(status.transcription);
+     * }
+     * ```
+     */
+    getTranscriptionStatus(jobId: string): Promise<TranscriptionJobStatus>;
+    /**
+     * Solicita una transcripcion de audio y recibe el resultado via SSE.
+     * Alternativa al polling para transcripciones asincronas.
+     *
+     * Requiere un entorno con EventSource nativo (navegador).
+     * Para Node.js se necesita un polyfill como 'eventsource'.
+     *
+     * @param audioBase64 - Audio codificado en base64
+     * @param audioFilename - Nombre del archivo con extension
+     * @param options - Opciones de streaming
+     * @returns Promesa que resuelve con el texto transcrito
+     *
+     * @example
+     * ```typescript
+     * const { transcription } = await sdk.ai.streamTranscription(
+     *   audioBase64,
+     *   'recording.webm',
+     *   { onProgress: (p) => console.log(`Progreso: ${p}%`) },
+     * );
+     * console.log(transcription);
+     * ```
+     */
+    streamTranscription(audioBase64: string, audioFilename: string, options?: StreamTranscriptionOptions): Promise<{
+        transcription: string;
+    }>;
+    /**
+     * Reporta un error del cliente al servidor para monitoreo.
+     * Este metodo nunca lanza excepciones; los errores de reporte se ignoran silenciosamente.
+     *
+     * @param params - Datos del error a reportar
+     *
+     * @example
+     * ```typescript
+     * await sdk.ai.reportError({
+     *   message: 'No se pudo cargar el widget',
+     *   code: 'WIDGET_LOAD_ERROR',
+     *   component: 'widget',
+     *   url: window.location.href,
+     *   userAgent: navigator.userAgent,
+     * });
+     * ```
+     */
+    reportError(params: {
+        message: string;
+        stack?: string;
+        code?: string;
+        component?: string;
+        context?: string;
+        endpoint?: string;
+        method?: string;
+        requestId?: string;
+        url?: string;
+        userAgent?: string;
+    }): Promise<void>;
     /**
      * Helper para esperar un tiempo
      */
@@ -828,7 +1015,14 @@ declare class UtiliaSDKError extends Error {
     readonly code: ErrorCode;
     /** Timestamp de cuando ocurrio el error */
     readonly timestamp: Date;
-    constructor(code: ErrorCode, message: string);
+    /** ID de la peticion que genero el error */
+    readonly requestId?: string;
+    /** Codigo de estado HTTP de la respuesta */
+    readonly statusCode?: number;
+    constructor(code: ErrorCode, message: string, options?: {
+        requestId?: string;
+        statusCode?: number;
+    });
     /**
      * Serializa el error a un objeto JSON
      */
@@ -837,6 +1031,8 @@ declare class UtiliaSDKError extends Error {
         code: ErrorCode;
         message: string;
         timestamp: string;
+        requestId: string | undefined;
+        statusCode: number | undefined;
     };
     /**
      * Verifica si el error es de tipo rate limit
@@ -943,4 +1139,4 @@ declare class UtiliaSDK {
     constructor(config: UtiliaSDKConfig);
 }
 
-export { type AddMessageInput, type AiJobStatus, type AiSuggestInput, type AiSuggestions, type AiUserAction, type CreateTicketInput, type CreateTicketUser, type CreatedMessage, type CreatedTicket, ErrorCode, type ExternalUser, type FileQuota, type GetSuggestionsOptions, type IdentifyUserInput, type MessageAuthor, type PaginatedResponse, type PaginationMeta, type RequestConfig, SDK_LIMITS, type TicketAttachment, type TicketCategory, type TicketContext, type TicketDetail, type TicketFilters, type TicketListItem, type TicketMessage, type TicketPriority, type TicketReporter, type TicketStatus, type TrackAiActionInput, type UnreadCount, type UploadFileOptions, type UploadedFile, UtiliaSDK, type UtiliaSDKConfig, UtiliaSDKError };
+export { type AddMessageInput, type AiJobStatus, type AiSuggestInput, type AiSuggestions, type AiUserAction, type CreateTicketInput, type CreateTicketUser, type CreatedMessage, type CreatedTicket, ErrorCode, type ExternalUser, type FileQuota, type GetSuggestionsOptions, type IdentifyUserInput, type MessageAuthor, type PaginatedResponse, type PaginationMeta, type RequestConfig, SDK_LIMITS, type SseEvent, type StreamSuggestionsHandle, type StreamSuggestionsOptions, type StreamTranscriptionOptions, type TicketAttachment, type TicketCategory, type TicketContext, type TicketDetail, type TicketFilters, type TicketListItem, type TicketMessage, type TicketPriority, type TicketReporter, type TicketStatus, type TrackAiActionInput, type TranscriptionJobStatus, type UnreadCount, type UploadFileOptions, type UploadedFile, UtiliaSDK, type UtiliaSDKConfig, UtiliaSDKError };

package/dist/index.d.ts

@@ -43,10 +43,22 @@ declare class UtiliaClient {
      * Ejecuta una funcion con reintentos y backoff exponencial
      */
     private executeWithRetry;
+    /**
+     * Genera un ID simple como fallback cuando crypto.randomUUID no esta disponible
+     */
+    private generateSimpleId;
     /**
      * Helper para esperar un tiempo
      */
     private sleep;
+    /**
+     * Construye una URL completa para conexiones SSE con la API key como query param.
+     * Util para EventSource que no soporta headers personalizados.
+     *
+     * @param path - Ruta relativa de la API (ej: /external/v1/tickets/ai-suggest/123/stream)
+     * @returns URL completa con apiKey como parametro de consulta
+     */
+    buildSseUrl(path: string): string;
     /**
      * Realiza una peticion GET
      */
@@ -672,6 +684,65 @@ interface GetSuggestionsOptions {
     /** Callback para reportar progreso */
     onProgress?: (progress: number) => void;
 }
+/**
+ * Evento SSE recibido durante el streaming de un job
+ */
+interface SseEvent {
+    /** Tipo de evento */
+    event: 'progress' | 'completed' | 'failed' | 'heartbeat';
+    /** Progreso actual (0-100) */
+    progress?: number;
+    /** Estado descriptivo */
+    status?: string;
+    /** Resultado del job (disponible en evento 'completed') */
+    result?: AiJobStatus['result'];
+    /** Mensaje de error (disponible en evento 'failed') */
+    error?: string;
+}
+/**
+ * Opciones para el metodo streamSuggestions
+ */
+interface StreamSuggestionsOptions {
+    /** Callback para reportar progreso (0-100) */
+    onProgress?: (progress: number) => void;
+    /** Callback para errores no fatales */
+    onError?: (error: Error) => void;
+    /** Timeout en ms (default: 120000) */
+    timeout?: number;
+}
+/**
+ * Handle retornado por streamSuggestions para controlar la conexion SSE
+ */
+interface StreamSuggestionsHandle {
+    /** Promesa que resuelve con el resultado cuando el job completa */
+    result: Promise<AiJobStatus['result']>;
+    /** Funcion para abortar la conexion SSE */
+    abort: () => void;
+}
+/**
+ * Estado del job de transcripcion asincrona
+ */
+interface TranscriptionJobStatus {
+    /** Estado actual del job */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Progreso del job (0-100) */
+    progress?: number;
+    /** Texto transcrito (disponible cuando status es 'completed') */
+    transcription?: string;
+    /** Mensaje de error (si status es 'failed') */
+    error?: string;
+}
+/**
+ * Opciones para el metodo streamTranscription
+ */
+interface StreamTranscriptionOptions {
+    /** Callback para reportar progreso (0-100) */
+    onProgress?: (progress: number) => void;
+    /** Callback para errores no fatales */
+    onError?: (error: Error) => void;
+    /** Timeout en ms (default: 120000) */
+    timeout?: number;
+}
 declare class AiService {
     private readonly client;
     private readonly basePath;
@@ -794,6 +865,122 @@ declare class AiService {
     trackAiAction(data: TrackAiActionInput): Promise<{
         success: boolean;
     }>;
+    /**
+     * Solicita sugerencias de IA y recibe el resultado via SSE (Server-Sent Events).
+     * Alternativa al polling que ofrece actualizaciones en tiempo real.
+     *
+     * Requiere un entorno con EventSource nativo (navegador).
+     * Para Node.js se necesita un polyfill como 'eventsource'.
+     *
+     * @param data - Datos para generar sugerencias
+     * @param options - Opciones de streaming
+     * @returns Handle con promesa de resultado y funcion de aborto
+     *
+     * @example
+     * ```typescript
+     * const handle = await sdk.ai.streamSuggestions(
+     *   { userId: 'user-123', text: 'No puedo iniciar sesion' },
+     *   { onProgress: (p) => console.log(`Progreso: ${p}%`) },
+     * );
+     *
+     * // Esperar resultado
+     * const result = await handle.result;
+     * console.log(result?.suggestions);
+     *
+     * // O abortar si el usuario cancela
+     * handle.abort();
+     * ```
+     */
+    streamSuggestions(data: AiSuggestInput, options?: StreamSuggestionsOptions): Promise<StreamSuggestionsHandle>;
+    /**
+     * Solicita una transcripcion de audio de forma asincrona.
+     * Retorna un jobId para consultar el estado o usar con streamTranscription.
+     *
+     * @param audioBase64 - Audio codificado en base64
+     * @param audioFilename - Nombre del archivo con extension
+     * @returns ID del job para consultar estado
+     *
+     * @example
+     * ```typescript
+     * const { jobId } = await sdk.ai.requestTranscription(
+     *   audioBase64,
+     *   'recording.webm',
+     * );
+     * ```
+     */
+    requestTranscription(audioBase64: string, audioFilename: string): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Obtiene el estado de un job de transcripcion asincrona.
+     *
+     * @param jobId - ID del job obtenido de requestTranscription
+     * @returns Estado actual del job de transcripcion
+     *
+     * @example
+     * ```typescript
+     * const status = await sdk.ai.getTranscriptionStatus(jobId);
+     *
+     * if (status.status === 'completed') {
+     *   console.log(status.transcription);
+     * }
+     * ```
+     */
+    getTranscriptionStatus(jobId: string): Promise<TranscriptionJobStatus>;
+    /**
+     * Solicita una transcripcion de audio y recibe el resultado via SSE.
+     * Alternativa al polling para transcripciones asincronas.
+     *
+     * Requiere un entorno con EventSource nativo (navegador).
+     * Para Node.js se necesita un polyfill como 'eventsource'.
+     *
+     * @param audioBase64 - Audio codificado en base64
+     * @param audioFilename - Nombre del archivo con extension
+     * @param options - Opciones de streaming
+     * @returns Promesa que resuelve con el texto transcrito
+     *
+     * @example
+     * ```typescript
+     * const { transcription } = await sdk.ai.streamTranscription(
+     *   audioBase64,
+     *   'recording.webm',
+     *   { onProgress: (p) => console.log(`Progreso: ${p}%`) },
+     * );
+     * console.log(transcription);
+     * ```
+     */
+    streamTranscription(audioBase64: string, audioFilename: string, options?: StreamTranscriptionOptions): Promise<{
+        transcription: string;
+    }>;
+    /**
+     * Reporta un error del cliente al servidor para monitoreo.
+     * Este metodo nunca lanza excepciones; los errores de reporte se ignoran silenciosamente.
+     *
+     * @param params - Datos del error a reportar
+     *
+     * @example
+     * ```typescript
+     * await sdk.ai.reportError({
+     *   message: 'No se pudo cargar el widget',
+     *   code: 'WIDGET_LOAD_ERROR',
+     *   component: 'widget',
+     *   url: window.location.href,
+     *   userAgent: navigator.userAgent,
+     * });
+     * ```
+     */
+    reportError(params: {
+        message: string;
+        stack?: string;
+        code?: string;
+        component?: string;
+        context?: string;
+        endpoint?: string;
+        method?: string;
+        requestId?: string;
+        url?: string;
+        userAgent?: string;
+    }): Promise<void>;
     /**
      * Helper para esperar un tiempo
      */
@@ -828,7 +1015,14 @@ declare class UtiliaSDKError extends Error {
     readonly code: ErrorCode;
     /** Timestamp de cuando ocurrio el error */
     readonly timestamp: Date;
-    constructor(code: ErrorCode, message: string);
+    /** ID de la peticion que genero el error */
+    readonly requestId?: string;
+    /** Codigo de estado HTTP de la respuesta */
+    readonly statusCode?: number;
+    constructor(code: ErrorCode, message: string, options?: {
+        requestId?: string;
+        statusCode?: number;
+    });
     /**
      * Serializa el error a un objeto JSON
      */
@@ -837,6 +1031,8 @@ declare class UtiliaSDKError extends Error {
         code: ErrorCode;
         message: string;
         timestamp: string;
+        requestId: string | undefined;
+        statusCode: number | undefined;
     };
     /**
      * Verifica si el error es de tipo rate limit
@@ -943,4 +1139,4 @@ declare class UtiliaSDK {
     constructor(config: UtiliaSDKConfig);
 }
 
-export { type AddMessageInput, type AiJobStatus, type AiSuggestInput, type AiSuggestions, type AiUserAction, type CreateTicketInput, type CreateTicketUser, type CreatedMessage, type CreatedTicket, ErrorCode, type ExternalUser, type FileQuota, type GetSuggestionsOptions, type IdentifyUserInput, type MessageAuthor, type PaginatedResponse, type PaginationMeta, type RequestConfig, SDK_LIMITS, type TicketAttachment, type TicketCategory, type TicketContext, type TicketDetail, type TicketFilters, type TicketListItem, type TicketMessage, type TicketPriority, type TicketReporter, type TicketStatus, type TrackAiActionInput, type UnreadCount, type UploadFileOptions, type UploadedFile, UtiliaSDK, type UtiliaSDKConfig, UtiliaSDKError };
+export { type AddMessageInput, type AiJobStatus, type AiSuggestInput, type AiSuggestions, type AiUserAction, type CreateTicketInput, type CreateTicketUser, type CreatedMessage, type CreatedTicket, ErrorCode, type ExternalUser, type FileQuota, type GetSuggestionsOptions, type IdentifyUserInput, type MessageAuthor, type PaginatedResponse, type PaginationMeta, type RequestConfig, SDK_LIMITS, type SseEvent, type StreamSuggestionsHandle, type StreamSuggestionsOptions, type StreamTranscriptionOptions, type TicketAttachment, type TicketCategory, type TicketContext, type TicketDetail, type TicketFilters, type TicketListItem, type TicketMessage, type TicketPriority, type TicketReporter, type TicketStatus, type TrackAiActionInput, type TranscriptionJobStatus, type UnreadCount, type UploadFileOptions, type UploadedFile, UtiliaSDK, type UtiliaSDKConfig, UtiliaSDKError };

package/dist/index.js

@@ -52,11 +52,13 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   return ErrorCode2;
 })(ErrorCode || {});
 var UtiliaSDKError = class _UtiliaSDKError extends Error {
-  constructor(code, message) {
+  constructor(code, message, options) {
     super(message);
     this.name = "UtiliaSDKError";
     this.code = code;
     this.timestamp = /* @__PURE__ */ new Date();
+    this.requestId = options?.requestId;
+    this.statusCode = options?.statusCode;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _UtiliaSDKError);
     }
@@ -69,7 +71,9 @@ var UtiliaSDKError = class _UtiliaSDKError extends Error {
       name: this.name,
       code: this.code,
       message: this.message,
-      timestamp: this.timestamp.toISOString()
+      timestamp: this.timestamp.toISOString(),
+      requestId: this.requestId,
+      statusCode: this.statusCode
     };
   }
   /**
@@ -109,6 +113,12 @@ var UtiliaClient = class {
         "X-Api-Key": this.config.apiKey
       }
     });
+    this.axios.interceptors.request.use((config2) => {
+      const requestId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : this.generateSimpleId();
+      config2.headers["x-request-id"] = requestId;
+      config2._requestId = requestId;
+      return config2;
+    });
     this.setupInterceptors();
   }
   /**
@@ -134,40 +144,43 @@ var UtiliaClient = class {
    * Convierte un error de Axios en un UtiliaSDKError
    */
   toSDKError(error) {
+    const requestId = error.response?.headers?.["x-request-id"] || error.config?._requestId;
+    const statusCode = error.response?.status;
+    const errorOptions = { requestId, statusCode };
     if (!error.response) {
       if (error.code === "ECONNABORTED") {
-        return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Timeout: la solicitud excedio el tiempo limite");
+        return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Timeout: la solicitud excedio el tiempo limite", errorOptions);
       }
-      return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Error de conexion: no se pudo conectar con el servidor");
+      return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Error de conexion: no se pudo conectar con el servidor", errorOptions);
     }
     const status = error.response.status;
     const data = error.response.data;
     const message = data?.message || data?.error || error.message;
     switch (status) {
       case 401:
-        return new UtiliaSDKError("UNAUTHORIZED" /* UNAUTHORIZED */, message || "API Key invalida o faltante");
+        return new UtiliaSDKError("UNAUTHORIZED" /* UNAUTHORIZED */, message || "API Key invalida o faltante", errorOptions);
       case 403:
         if (message?.toLowerCase().includes("rate limit")) {
-          return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, "Rate limit excedido. Intenta de nuevo mas tarde.");
+          return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, "Rate limit excedido. Intenta de nuevo mas tarde.", errorOptions);
         }
         if (message?.toLowerCase().includes("origen")) {
-          return new UtiliaSDKError("FORBIDDEN" /* FORBIDDEN */, "Origen no permitido por CORS");
+          return new UtiliaSDKError("FORBIDDEN" /* FORBIDDEN */, "Origen no permitido por CORS", errorOptions);
         }
-        return new UtiliaSDKError("FORBIDDEN" /* FORBIDDEN */, message || "Acceso denegado");
+        return new UtiliaSDKError("FORBIDDEN" /* FORBIDDEN */, message || "Acceso denegado", errorOptions);
       case 404:
-        return new UtiliaSDKError("NOT_FOUND" /* NOT_FOUND */, message || "Recurso no encontrado");
+        return new UtiliaSDKError("NOT_FOUND" /* NOT_FOUND */, message || "Recurso no encontrado", errorOptions);
       case 400:
       case 422:
-        return new UtiliaSDKError("VALIDATION_ERROR" /* VALIDATION_ERROR */, message || "Error de validacion en los datos enviados");
+        return new UtiliaSDKError("VALIDATION_ERROR" /* VALIDATION_ERROR */, message || "Error de validacion en los datos enviados", errorOptions);
       case 429:
-        return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, message || "Rate limit excedido. Intenta de nuevo mas tarde.");
+        return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, message || "Rate limit excedido. Intenta de nuevo mas tarde.", errorOptions);
       case 500:
       case 502:
       case 503:
       case 504:
-        return new UtiliaSDKError("UNKNOWN" /* UNKNOWN */, message || "Error interno del servidor");
+        return new UtiliaSDKError("UNKNOWN" /* UNKNOWN */, message || "Error interno del servidor", errorOptions);
       default:
-        return new UtiliaSDKError("UNKNOWN" /* UNKNOWN */, message || `Error desconocido (HTTP ${status})`);
+        return new UtiliaSDKError("UNKNOWN" /* UNKNOWN */, message || `Error desconocido (HTTP ${status})`, errorOptions);
     }
   }
   /**
@@ -214,12 +227,30 @@ var UtiliaClient = class {
     }
     throw lastError;
   }
+  /**
+   * Genera un ID simple como fallback cuando crypto.randomUUID no esta disponible
+   */
+  generateSimpleId() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+  }
   /**
    * Helper para esperar un tiempo
    */
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+  /**
+   * Construye una URL completa para conexiones SSE con la API key como query param.
+   * Util para EventSource que no soporta headers personalizados.
+   *
+   * @param path - Ruta relativa de la API (ej: /external/v1/tickets/ai-suggest/123/stream)
+   * @returns URL completa con apiKey como parametro de consulta
+   */
+  buildSseUrl(path) {
+    const base = this.config.baseURL.replace(/\/$/, "");
+    const separator = path.includes("?") ? "&" : "?";
+    return `${base}${path}${separator}apiKey=${this.config.apiKey}`;
+  }
   /**
    * Realiza una peticion GET
    */
@@ -792,6 +823,237 @@ var AiService = class {
   async trackAiAction(data) {
     return this.client.post(`${this.basePath}/ai-track-action`, data);
   }
+  /**
+   * Solicita sugerencias de IA y recibe el resultado via SSE (Server-Sent Events).
+   * Alternativa al polling que ofrece actualizaciones en tiempo real.
+   *
+   * Requiere un entorno con EventSource nativo (navegador).
+   * Para Node.js se necesita un polyfill como 'eventsource'.
+   *
+   * @param data - Datos para generar sugerencias
+   * @param options - Opciones de streaming
+   * @returns Handle con promesa de resultado y funcion de aborto
+   *
+   * @example
+   * ```typescript
+   * const handle = await sdk.ai.streamSuggestions(
+   *   { userId: 'user-123', text: 'No puedo iniciar sesion' },
+   *   { onProgress: (p) => console.log(`Progreso: ${p}%`) },
+   * );
+   *
+   * // Esperar resultado
+   * const result = await handle.result;
+   * console.log(result?.suggestions);
+   *
+   * // O abortar si el usuario cancela
+   * handle.abort();
+   * ```
+   */
+  async streamSuggestions(data, options = {}) {
+    const { onProgress, onError, timeout = 12e4 } = options;
+    if (typeof EventSource === "undefined") {
+      throw new Error(
+        'EventSource no esta disponible en este entorno. Para Node.js, instala un polyfill como "eventsource" y asignalo a globalThis.EventSource.'
+      );
+    }
+    const { jobId } = await this.requestSuggestions(data);
+    const sseUrl = this.client.buildSseUrl(`${this.basePath}/ai-suggest/${jobId}/stream`);
+    let eventSource;
+    let timeoutId;
+    const result = new Promise((resolve, reject) => {
+      eventSource = new EventSource(sseUrl);
+      timeoutId = setTimeout(() => {
+        eventSource.close();
+        reject(new Error("Timeout: la conexion SSE excedio el tiempo limite"));
+      }, timeout);
+      eventSource.onmessage = (event) => {
+        try {
+          const data2 = JSON.parse(event.data);
+          switch (data2.event) {
+            case "progress":
+              if (onProgress && data2.progress !== void 0) {
+                onProgress(data2.progress);
+              }
+              break;
+            case "completed":
+              clearTimeout(timeoutId);
+              eventSource.close();
+              resolve(data2.result);
+              break;
+            case "failed":
+              clearTimeout(timeoutId);
+              eventSource.close();
+              reject(new Error(data2.error || "Error al generar sugerencias"));
+              break;
+            case "heartbeat":
+              break;
+          }
+        } catch (parseError) {
+          if (onError) {
+            onError(new Error("Error al parsear evento SSE"));
+          }
+        }
+      };
+      eventSource.onerror = () => {
+        clearTimeout(timeoutId);
+        eventSource.close();
+        reject(new Error("Error en la conexion SSE"));
+      };
+    });
+    const abort = () => {
+      clearTimeout(timeoutId);
+      eventSource?.close();
+    };
+    return { result, abort };
+  }
+  /**
+   * Solicita una transcripcion de audio de forma asincrona.
+   * Retorna un jobId para consultar el estado o usar con streamTranscription.
+   *
+   * @param audioBase64 - Audio codificado en base64
+   * @param audioFilename - Nombre del archivo con extension
+   * @returns ID del job para consultar estado
+   *
+   * @example
+   * ```typescript
+   * const { jobId } = await sdk.ai.requestTranscription(
+   *   audioBase64,
+   *   'recording.webm',
+   * );
+   * ```
+   */
+  async requestTranscription(audioBase64, audioFilename) {
+    return this.client.post(`${this.basePath}/ai-transcribe-async`, {
+      audioBase64,
+      audioFilename
+    });
+  }
+  /**
+   * Obtiene el estado de un job de transcripcion asincrona.
+   *
+   * @param jobId - ID del job obtenido de requestTranscription
+   * @returns Estado actual del job de transcripcion
+   *
+   * @example
+   * ```typescript
+   * const status = await sdk.ai.getTranscriptionStatus(jobId);
+   *
+   * if (status.status === 'completed') {
+   *   console.log(status.transcription);
+   * }
+   * ```
+   */
+  async getTranscriptionStatus(jobId) {
+    return this.client.get(`${this.basePath}/ai-transcribe/${jobId}`);
+  }
+  /**
+   * Solicita una transcripcion de audio y recibe el resultado via SSE.
+   * Alternativa al polling para transcripciones asincronas.
+   *
+   * Requiere un entorno con EventSource nativo (navegador).
+   * Para Node.js se necesita un polyfill como 'eventsource'.
+   *
+   * @param audioBase64 - Audio codificado en base64
+   * @param audioFilename - Nombre del archivo con extension
+   * @param options - Opciones de streaming
+   * @returns Promesa que resuelve con el texto transcrito
+   *
+   * @example
+   * ```typescript
+   * const { transcription } = await sdk.ai.streamTranscription(
+   *   audioBase64,
+   *   'recording.webm',
+   *   { onProgress: (p) => console.log(`Progreso: ${p}%`) },
+   * );
+   * console.log(transcription);
+   * ```
+   */
+  async streamTranscription(audioBase64, audioFilename, options = {}) {
+    const { onProgress, onError, timeout = 12e4 } = options;
+    if (typeof EventSource === "undefined") {
+      throw new Error(
+        'EventSource no esta disponible en este entorno. Para Node.js, instala un polyfill como "eventsource" y asignalo a globalThis.EventSource.'
+      );
+    }
+    const { jobId } = await this.requestTranscription(audioBase64, audioFilename);
+    const sseUrl = this.client.buildSseUrl(`${this.basePath}/ai-transcribe/${jobId}/stream`);
+    return new Promise((resolve, reject) => {
+      const eventSource = new EventSource(sseUrl);
+      const timeoutId = setTimeout(() => {
+        eventSource.close();
+        reject(new Error("Timeout: la conexion SSE excedio el tiempo limite"));
+      }, timeout);
+      eventSource.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          switch (data.event) {
+            case "progress":
+              if (onProgress && data.progress !== void 0) {
+                onProgress(data.progress);
+              }
+              break;
+            case "completed":
+              clearTimeout(timeoutId);
+              eventSource.close();
+              resolve({ transcription: data.result?.transcription || "" });
+              break;
+            case "failed":
+              clearTimeout(timeoutId);
+              eventSource.close();
+              reject(new Error(data.error || "Error en la transcripcion"));
+              break;
+            case "heartbeat":
+              break;
+          }
+        } catch (parseError) {
+          if (onError) {
+            onError(new Error("Error al parsear evento SSE"));
+          }
+        }
+      };
+      eventSource.onerror = () => {
+        clearTimeout(timeoutId);
+        eventSource.close();
+        reject(new Error("Error en la conexion SSE"));
+      };
+    });
+  }
+  /**
+   * Reporta un error del cliente al servidor para monitoreo.
+   * Este metodo nunca lanza excepciones; los errores de reporte se ignoran silenciosamente.
+   *
+   * @param params - Datos del error a reportar
+   *
+   * @example
+   * ```typescript
+   * await sdk.ai.reportError({
+   *   message: 'No se pudo cargar el widget',
+   *   code: 'WIDGET_LOAD_ERROR',
+   *   component: 'widget',
+   *   url: window.location.href,
+   *   userAgent: navigator.userAgent,
+   * });
+   * ```
+   */
+  async reportError(params) {
+    try {
+      await this.client.post(`${this.basePath}/client-errors`, {
+        errors: [{
+          message: params.message,
+          stack: params.stack,
+          code: params.code,
+          severity: "low",
+          component: params.component || "sdk",
+          endpoint: params.endpoint,
+          method: params.method,
+          requestId: params.requestId,
+          url: params.url,
+          userAgent: params.userAgent
+        }]
+      });
+    } catch {
+    }
+  }
   /**
    * Helper para esperar un tiempo
    */

package/dist/index.mjs

@@ -13,11 +13,13 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   return ErrorCode2;
 })(ErrorCode || {});
 var UtiliaSDKError = class _UtiliaSDKError extends Error {
-  constructor(code, message) {
+  constructor(code, message, options) {
     super(message);
     this.name = "UtiliaSDKError";
     this.code = code;
     this.timestamp = /* @__PURE__ */ new Date();
+    this.requestId = options?.requestId;
+    this.statusCode = options?.statusCode;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _UtiliaSDKError);
     }
@@ -30,7 +32,9 @@ var UtiliaSDKError = class _UtiliaSDKError extends Error {
       name: this.name,
       code: this.code,
       message: this.message,
-      timestamp: this.timestamp.toISOString()
+      timestamp: this.timestamp.toISOString(),
+      requestId: this.requestId,
+      statusCode: this.statusCode
     };
   }
   /**
@@ -70,6 +74,12 @@ var UtiliaClient = class {
         "X-Api-Key": this.config.apiKey
       }
     });
+    this.axios.interceptors.request.use((config2) => {
+      const requestId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : this.generateSimpleId();
+      config2.headers["x-request-id"] = requestId;
+      config2._requestId = requestId;
+      return config2;
+    });
     this.setupInterceptors();
   }
   /**
@@ -95,40 +105,43 @@ var UtiliaClient = class {
    * Convierte un error de Axios en un UtiliaSDKError
    */
   toSDKError(error) {
+    const requestId = error.response?.headers?.["x-request-id"] || error.config?._requestId;
+    const statusCode = error.response?.status;
+    const errorOptions = { requestId, statusCode };
     if (!error.response) {
       if (error.code === "ECONNABORTED") {
-        return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Timeout: la solicitud excedio el tiempo limite");
+        return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Timeout: la solicitud excedio el tiempo limite", errorOptions);
       }
-      return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Error de conexion: no se pudo conectar con el servidor");
+      return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Error de conexion: no se pudo conectar con el servidor", errorOptions);
     }
     const status = error.response.status;
     const data = error.response.data;
     const message = data?.message || data?.error || error.message;
     switch (status) {
       case 401:
-        return new UtiliaSDKError("UNAUTHORIZED" /* UNAUTHORIZED */, message || "API Key invalida o faltante");
+        return new UtiliaSDKError("UNAUTHORIZED" /* UNAUTHORIZED */, message || "API Key invalida o faltante", errorOptions);
       case 403:
         if (message?.toLowerCase().includes("rate limit")) {
-          return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, "Rate limit excedido. Intenta de nuevo mas tarde.");
+          return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, "Rate limit excedido. Intenta de nuevo mas tarde.", errorOptions);
         }
         if (message?.toLowerCase().includes("origen")) {
-          return new UtiliaSDKError("FORBIDDEN" /* FORBIDDEN */, "Origen no permitido por CORS");
+          return new UtiliaSDKError("FORBIDDEN" /* FORBIDDEN */, "Origen no permitido por CORS", errorOptions);
         }
-        return new UtiliaSDKError("FORBIDDEN" /* FORBIDDEN */, message || "Acceso denegado");
+        return new UtiliaSDKError("FORBIDDEN" /* FORBIDDEN */, message || "Acceso denegado", errorOptions);
       case 404:
-        return new UtiliaSDKError("NOT_FOUND" /* NOT_FOUND */, message || "Recurso no encontrado");
+        return new UtiliaSDKError("NOT_FOUND" /* NOT_FOUND */, message || "Recurso no encontrado", errorOptions);
       case 400:
       case 422:
-        return new UtiliaSDKError("VALIDATION_ERROR" /* VALIDATION_ERROR */, message || "Error de validacion en los datos enviados");
+        return new UtiliaSDKError("VALIDATION_ERROR" /* VALIDATION_ERROR */, message || "Error de validacion en los datos enviados", errorOptions);
       case 429:
-        return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, message || "Rate limit excedido. Intenta de nuevo mas tarde.");
+        return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, message || "Rate limit excedido. Intenta de nuevo mas tarde.", errorOptions);
       case 500:
       case 502:
       case 503:
       case 504:
-        return new UtiliaSDKError("UNKNOWN" /* UNKNOWN */, message || "Error interno del servidor");
+        return new UtiliaSDKError("UNKNOWN" /* UNKNOWN */, message || "Error interno del servidor", errorOptions);
       default:
-        return new UtiliaSDKError("UNKNOWN" /* UNKNOWN */, message || `Error desconocido (HTTP ${status})`);
+        return new UtiliaSDKError("UNKNOWN" /* UNKNOWN */, message || `Error desconocido (HTTP ${status})`, errorOptions);
     }
   }
   /**
@@ -175,12 +188,30 @@ var UtiliaClient = class {
     }
     throw lastError;
   }
+  /**
+   * Genera un ID simple como fallback cuando crypto.randomUUID no esta disponible
+   */
+  generateSimpleId() {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+  }
   /**
    * Helper para esperar un tiempo
    */
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+  /**
+   * Construye una URL completa para conexiones SSE con la API key como query param.
+   * Util para EventSource que no soporta headers personalizados.
+   *
+   * @param path - Ruta relativa de la API (ej: /external/v1/tickets/ai-suggest/123/stream)
+   * @returns URL completa con apiKey como parametro de consulta
+   */
+  buildSseUrl(path) {
+    const base = this.config.baseURL.replace(/\/$/, "");
+    const separator = path.includes("?") ? "&" : "?";
+    return `${base}${path}${separator}apiKey=${this.config.apiKey}`;
+  }
   /**
    * Realiza una peticion GET
    */
@@ -753,6 +784,237 @@ var AiService = class {
   async trackAiAction(data) {
     return this.client.post(`${this.basePath}/ai-track-action`, data);
   }
+  /**
+   * Solicita sugerencias de IA y recibe el resultado via SSE (Server-Sent Events).
+   * Alternativa al polling que ofrece actualizaciones en tiempo real.
+   *
+   * Requiere un entorno con EventSource nativo (navegador).
+   * Para Node.js se necesita un polyfill como 'eventsource'.
+   *
+   * @param data - Datos para generar sugerencias
+   * @param options - Opciones de streaming
+   * @returns Handle con promesa de resultado y funcion de aborto
+   *
+   * @example
+   * ```typescript
+   * const handle = await sdk.ai.streamSuggestions(
+   *   { userId: 'user-123', text: 'No puedo iniciar sesion' },
+   *   { onProgress: (p) => console.log(`Progreso: ${p}%`) },
+   * );
+   *
+   * // Esperar resultado
+   * const result = await handle.result;
+   * console.log(result?.suggestions);
+   *
+   * // O abortar si el usuario cancela
+   * handle.abort();
+   * ```
+   */
+  async streamSuggestions(data, options = {}) {
+    const { onProgress, onError, timeout = 12e4 } = options;
+    if (typeof EventSource === "undefined") {
+      throw new Error(
+        'EventSource no esta disponible en este entorno. Para Node.js, instala un polyfill como "eventsource" y asignalo a globalThis.EventSource.'
+      );
+    }
+    const { jobId } = await this.requestSuggestions(data);
+    const sseUrl = this.client.buildSseUrl(`${this.basePath}/ai-suggest/${jobId}/stream`);
+    let eventSource;
+    let timeoutId;
+    const result = new Promise((resolve, reject) => {
+      eventSource = new EventSource(sseUrl);
+      timeoutId = setTimeout(() => {
+        eventSource.close();
+        reject(new Error("Timeout: la conexion SSE excedio el tiempo limite"));
+      }, timeout);
+      eventSource.onmessage = (event) => {
+        try {
+          const data2 = JSON.parse(event.data);
+          switch (data2.event) {
+            case "progress":
+              if (onProgress && data2.progress !== void 0) {
+                onProgress(data2.progress);
+              }
+              break;
+            case "completed":
+              clearTimeout(timeoutId);
+              eventSource.close();
+              resolve(data2.result);
+              break;
+            case "failed":
+              clearTimeout(timeoutId);
+              eventSource.close();
+              reject(new Error(data2.error || "Error al generar sugerencias"));
+              break;
+            case "heartbeat":
+              break;
+          }
+        } catch (parseError) {
+          if (onError) {
+            onError(new Error("Error al parsear evento SSE"));
+          }
+        }
+      };
+      eventSource.onerror = () => {
+        clearTimeout(timeoutId);
+        eventSource.close();
+        reject(new Error("Error en la conexion SSE"));
+      };
+    });
+    const abort = () => {
+      clearTimeout(timeoutId);
+      eventSource?.close();
+    };
+    return { result, abort };
+  }
+  /**
+   * Solicita una transcripcion de audio de forma asincrona.
+   * Retorna un jobId para consultar el estado o usar con streamTranscription.
+   *
+   * @param audioBase64 - Audio codificado en base64
+   * @param audioFilename - Nombre del archivo con extension
+   * @returns ID del job para consultar estado
+   *
+   * @example
+   * ```typescript
+   * const { jobId } = await sdk.ai.requestTranscription(
+   *   audioBase64,
+   *   'recording.webm',
+   * );
+   * ```
+   */
+  async requestTranscription(audioBase64, audioFilename) {
+    return this.client.post(`${this.basePath}/ai-transcribe-async`, {
+      audioBase64,
+      audioFilename
+    });
+  }
+  /**
+   * Obtiene el estado de un job de transcripcion asincrona.
+   *
+   * @param jobId - ID del job obtenido de requestTranscription
+   * @returns Estado actual del job de transcripcion
+   *
+   * @example
+   * ```typescript
+   * const status = await sdk.ai.getTranscriptionStatus(jobId);
+   *
+   * if (status.status === 'completed') {
+   *   console.log(status.transcription);
+   * }
+   * ```
+   */
+  async getTranscriptionStatus(jobId) {
+    return this.client.get(`${this.basePath}/ai-transcribe/${jobId}`);
+  }
+  /**
+   * Solicita una transcripcion de audio y recibe el resultado via SSE.
+   * Alternativa al polling para transcripciones asincronas.
+   *
+   * Requiere un entorno con EventSource nativo (navegador).
+   * Para Node.js se necesita un polyfill como 'eventsource'.
+   *
+   * @param audioBase64 - Audio codificado en base64
+   * @param audioFilename - Nombre del archivo con extension
+   * @param options - Opciones de streaming
+   * @returns Promesa que resuelve con el texto transcrito
+   *
+   * @example
+   * ```typescript
+   * const { transcription } = await sdk.ai.streamTranscription(
+   *   audioBase64,
+   *   'recording.webm',
+   *   { onProgress: (p) => console.log(`Progreso: ${p}%`) },
+   * );
+   * console.log(transcription);
+   * ```
+   */
+  async streamTranscription(audioBase64, audioFilename, options = {}) {
+    const { onProgress, onError, timeout = 12e4 } = options;
+    if (typeof EventSource === "undefined") {
+      throw new Error(
+        'EventSource no esta disponible en este entorno. Para Node.js, instala un polyfill como "eventsource" y asignalo a globalThis.EventSource.'
+      );
+    }
+    const { jobId } = await this.requestTranscription(audioBase64, audioFilename);
+    const sseUrl = this.client.buildSseUrl(`${this.basePath}/ai-transcribe/${jobId}/stream`);
+    return new Promise((resolve, reject) => {
+      const eventSource = new EventSource(sseUrl);
+      const timeoutId = setTimeout(() => {
+        eventSource.close();
+        reject(new Error("Timeout: la conexion SSE excedio el tiempo limite"));
+      }, timeout);
+      eventSource.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          switch (data.event) {
+            case "progress":
+              if (onProgress && data.progress !== void 0) {
+                onProgress(data.progress);
+              }
+              break;
+            case "completed":
+              clearTimeout(timeoutId);
+              eventSource.close();
+              resolve({ transcription: data.result?.transcription || "" });
+              break;
+            case "failed":
+              clearTimeout(timeoutId);
+              eventSource.close();
+              reject(new Error(data.error || "Error en la transcripcion"));
+              break;
+            case "heartbeat":
+              break;
+          }
+        } catch (parseError) {
+          if (onError) {
+            onError(new Error("Error al parsear evento SSE"));
+          }
+        }
+      };
+      eventSource.onerror = () => {
+        clearTimeout(timeoutId);
+        eventSource.close();
+        reject(new Error("Error en la conexion SSE"));
+      };
+    });
+  }
+  /**
+   * Reporta un error del cliente al servidor para monitoreo.
+   * Este metodo nunca lanza excepciones; los errores de reporte se ignoran silenciosamente.
+   *
+   * @param params - Datos del error a reportar
+   *
+   * @example
+   * ```typescript
+   * await sdk.ai.reportError({
+   *   message: 'No se pudo cargar el widget',
+   *   code: 'WIDGET_LOAD_ERROR',
+   *   component: 'widget',
+   *   url: window.location.href,
+   *   userAgent: navigator.userAgent,
+   * });
+   * ```
+   */
+  async reportError(params) {
+    try {
+      await this.client.post(`${this.basePath}/client-errors`, {
+        errors: [{
+          message: params.message,
+          stack: params.stack,
+          code: params.code,
+          severity: "low",
+          component: params.component || "sdk",
+          endpoint: params.endpoint,
+          method: params.method,
+          requestId: params.requestId,
+          url: params.url,
+          userAgent: params.userAgent
+        }]
+      });
+    } catch {
+    }
+  }
   /**
    * Helper para esperar un tiempo
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilia-os/sdk-js",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "SDK JavaScript/TypeScript para UTILIA OS External Integrations",
   "main": "dist/index.js",
   "module": "dist/index.mjs",