@utilia-os/sdk-js 1.2.0 → 1.4.0

package/README.md

@@ -2,13 +2,13 @@
 
 SDK JavaScript/TypeScript para integrar aplicaciones externas con UTILIA OS.
 
-## Instalacion
+## Instalación
 
 ```bash
 npm install @utilia-os/sdk-js
 ```
 
-## Configuracion
+## Configuración
 
 ```typescript
 import { UtiliaSDK } from '@utilia-os/sdk-js';
@@ -29,7 +29,7 @@ Antes de crear tickets, identifica al usuario en tu sistema:
 
 ```typescript
 const user = await sdk.users.identify({
-  externalId: 'user-123',           // ID unico en tu sistema (requerido)
+  externalId: 'user-123',           // ID único en tu sistema (requerido)
   email: 'user@example.com',        // opcional
   name: 'Juan Perez',               // opcional
   avatarUrl: 'https://...',         // opcional
@@ -49,10 +49,10 @@ const ticket = await sdk.tickets.create({
     email: 'user@example.com',
     name: 'Juan Perez',
   },
-  title: 'Problema con la facturacion',
+  title: 'Problema con la facturación',
   description: 'No puedo ver mis facturas del mes pasado...',
   category: 'PROBLEMA',  // CONSULTA | PROBLEMA | SUGERENCIA | OTRO
-  priority: 'MEDIA',     // BAJA | MEDIA | ALTA | CRITICA
+  priority: 'MEDIA',     // BAJA | MEDIA | ALTA | CRÍTICA
   context: {             // opcional
     url: window.location.href,
     appVersion: '1.2.3',
@@ -104,7 +104,7 @@ await sdk.tickets.close('ticket-uuid', 'user-123');
 await sdk.tickets.reopen('ticket-uuid', 'user-123');
 ```
 
-### Obtener Mensajes No Leidos
+### Obtener Mensajes No Leídos
 
 ```typescript
 const { count } = await sdk.tickets.getUnreadCount('user-123');
@@ -113,6 +113,50 @@ if (count > 0) {
 }
 ```
 
+### Reportar Error
+
+```typescript
+const result = await sdk.errors.report({
+  message: 'Error al procesar pago',
+  module: 'payment-processor',
+  severity: 'critical',
+  stack: error.stack,
+  endpoint: '/api/payments',
+  method: 'POST',
+  context: {
+    gatewayId: 'stripe',
+    orderId: 'order-456',
+  },
+});
+
+console.log(result.hash);          // Hash único del error
+console.log(result.deduplicated);   // true si el error ya existía
+```
+
+### Listar Errores
+
+```typescript
+const result = await sdk.errors.list({
+  severity: ['critical', 'high'],
+  resolved: false,
+  limit: 20,
+});
+
+console.log(result.errors);
+console.log(result.pagination.total);
+```
+
+### Estadísticas de Errores
+
+```typescript
+const stats = await sdk.errors.stats();
+
+console.log(stats.total);        // Total de errores
+console.log(stats.unresolved);   // Errores sin resolver
+console.log(stats.bySeverity);   // { critical: 5, high: 10, ... }
+console.log(stats.byModule);     // { auth: 3, payments: 7, ... }
+```
+
 ## Manejo de Errores
 
 ```typescript
@@ -124,13 +168,13 @@ try {
   if (error instanceof UtiliaSDKError) {
     switch (error.code) {
       case ErrorCode.UNAUTHORIZED:
-        console.error('API Key invalida');
+        console.error('API Key inválida');
         break;
       case ErrorCode.RATE_LIMITED:
         console.error('Demasiadas peticiones, espera antes de reintentar');
         break;
       case ErrorCode.VALIDATION_ERROR:
-        console.error('Datos invalidos:', error.message);
+        console.error('Datos inválidos:', error.message);
         break;
       case ErrorCode.NOT_FOUND:
         console.error('Recurso no encontrado');
@@ -141,7 +185,7 @@ try {
 
     // Verificar si se puede reintentar
     if (error.isRetryable()) {
-      // Implementar logica de reintento
+      // Implementar lógica de reintento
     }
   }
 }
@@ -153,7 +197,7 @@ El SDK exporta todos los tipos TypeScript necesarios:
 
 ```typescript
 import type {
-  // Configuracion
+  // Configuración
   UtiliaSDKConfig,
 
   // Tickets
@@ -169,6 +213,13 @@ import type {
   IdentifyUserInput,
   ExternalUser,
 
+  // Errores del sistema
+  ReportErrorInput,
+  ReportedError,
+  SystemError,
+  ErrorFilters,
+  ErrorStats,
+
   // Comunes
   TicketStatus,
   TicketCategory,

package/dist/index.d.mts

@@ -85,6 +85,23 @@ declare class UtiliaClient {
     postForm<T>(url: string, formData: FormData, onProgress?: (progress: number) => void): Promise<T>;
 }
 
+/**
+ * Tipos comunes compartidos en el SDK
+ */
+type TicketStatus = 'OPEN' | 'IN_REVIEW' | 'RESOLVED' | 'CLOSED';
+type TicketCategory = 'CONSULTA' | 'PROBLEMA' | 'SUGERENCIA' | 'OTRO';
+type TicketPriority = 'BAJA' | 'MEDIA' | 'ALTA' | 'CRITICA';
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: PaginationMeta;
+}
+
 /**
  * Tipos relacionados con archivos adjuntos
  */
@@ -130,69 +147,6 @@ interface FileQuota {
     usagePercent: number;
 }
 
-/**
- * Servicio de archivos adjuntos
- * Permite subir archivos para adjuntar a tickets
- */
-
-declare class FilesService {
-    private readonly client;
-    private readonly basePath;
-    constructor(client: UtiliaClient);
-    /**
-     * Subir un archivo para adjuntar a tickets
-     *
-     * @param file - Archivo a subir (File o Blob)
-     * @param options - Opciones de subida
-     * @returns Archivo subido con su ID
-     *
-     * @example Browser
-     * ```typescript
-     * // Desde input file
-     * const input = document.querySelector('input[type="file"]');
-     * const file = input.files[0];
-     * const uploaded = await sdk.files.upload(file);
-     *
-     * // Usar en ticket
-     * await sdk.tickets.create({
-     *   ...ticketData,
-     *   attachmentIds: [uploaded.id],
-     * });
-     * ```
-     */
-    upload(file: File | Blob, options?: UploadFileOptions): Promise<UploadedFile>;
-    /**
-     * Obtener URL de descarga para un archivo
-     *
-     * @param fileId - ID del archivo
-     * @returns URL temporal de descarga
-     */
-    getUrl(fileId: string): Promise<string>;
-    /**
-     * Obtener informacion de quota de almacenamiento
-     *
-     * @returns Informacion de uso y limites
-     */
-    getQuota(): Promise<FileQuota>;
-}
-
-/**
- * Tipos comunes compartidos en el SDK
- */
-type TicketStatus = 'OPEN' | 'IN_REVIEW' | 'RESOLVED' | 'CLOSED';
-type TicketCategory = 'CONSULTA' | 'PROBLEMA' | 'SUGERENCIA' | 'OTRO';
-type TicketPriority = 'BAJA' | 'MEDIA' | 'ALTA' | 'CRITICA';
-interface PaginationMeta {
-    page: number;
-    limit: number;
-    total: number;
-    totalPages: number;
-}
-interface PaginatedResponse<T> {
-    data: T[];
-    pagination: PaginationMeta;
-}
-
 /**
  * Tipos relacionados con tickets de soporte
  */
@@ -410,6 +364,237 @@ interface ExternalUser {
     };
 }
 
+/**
+ * Tipos relacionados con errores del sistema
+ */
+/**
+ * Nivel de severidad de un error
+ */
+type ErrorSeverity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * Metodo HTTP asociado a un error
+ */
+type ErrorHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Datos de entrada para reportar un error
+ */
+interface ReportErrorInput {
+    /** Mensaje descriptivo del error (1-2000 caracteres) */
+    message: string;
+    /** Nivel de severidad del error */
+    severity?: ErrorSeverity;
+    /** Modulo o area donde ocurrio el error (1-100 caracteres) */
+    module: string;
+    /** Stack trace del error */
+    stack?: string;
+    /** Archivo donde ocurrio el error */
+    file?: string;
+    /** Linea del archivo donde ocurrio el error */
+    line?: number;
+    /** Funcion donde ocurrio el error */
+    function?: string;
+    /** Endpoint relacionado con el error */
+    endpoint?: string;
+    /** Metodo HTTP de la peticion que causo el error */
+    method?: ErrorHttpMethod;
+    /** ID del usuario afectado */
+    userId?: string;
+    /** ID de la peticion donde ocurrio el error */
+    requestId?: string;
+    /** Contexto adicional del error */
+    context?: Record<string, unknown>;
+}
+/**
+ * Respuesta al reportar un error
+ */
+interface ReportedError {
+    /** Indica si el error fue registrado correctamente */
+    success: boolean;
+    /** Hash unico del error (para deduplicacion) */
+    hash: string;
+    /** Indica si el error ya existia y se incremento su contador */
+    deduplicated: boolean;
+}
+/**
+ * Error del sistema en listados
+ */
+interface SystemError {
+    /** ID unico del error */
+    id: string;
+    /** Hash de deduplicacion */
+    hash: string;
+    /** Mensaje del error */
+    message: string;
+    /** Modulo donde ocurrio */
+    module: string;
+    /** Nivel de severidad */
+    severity: ErrorSeverity;
+    /** Archivo donde ocurrio */
+    file?: string;
+    /** Linea del archivo */
+    line?: number;
+    /** Endpoint relacionado */
+    endpoint?: string;
+    /** Numero de ocurrencias */
+    count: number;
+    /** Fecha de la primera ocurrencia */
+    firstOccurrence: string;
+    /** Fecha de la ultima ocurrencia */
+    lastOccurrence: string;
+    /** Indica si el error esta resuelto */
+    resolved: boolean;
+    /** Fecha en que se resolvio */
+    resolvedAt?: string;
+}
+/**
+ * Filtros para listar errores
+ */
+interface ErrorFilters {
+    /** Filtrar por niveles de severidad */
+    severity?: ErrorSeverity[];
+    /** Filtrar por modulo */
+    module?: string;
+    /** Filtrar por estado de resolucion */
+    resolved?: boolean;
+    /** Numero maximo de resultados (default: 50, max: 200) */
+    limit?: number;
+    /** Desplazamiento para paginacion */
+    offset?: number;
+    /** Fecha de inicio (ISO 8601) */
+    from?: string;
+    /** Fecha de fin (ISO 8601) */
+    to?: string;
+}
+/**
+ * Estadisticas de errores
+ */
+interface ErrorStats {
+    /** Total de errores registrados */
+    total: number;
+    /** Errores sin resolver */
+    unresolved: number;
+    /** Distribucion por severidad */
+    bySeverity: Record<string, number>;
+    /** Distribucion por modulo */
+    byModule: Record<string, number>;
+    /** Errores mas frecuentes */
+    topErrors: Array<{
+        hash: string;
+        message: string;
+        count: number;
+        severity: string;
+    }>;
+}
+
+/**
+ * Servicio de errores del sistema
+ * Maneja todas las operaciones relacionadas con el reporte y consulta de errores
+ */
+
+declare class ErrorsService {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: UtiliaClient);
+    /**
+     * Reportar un error del sistema
+     *
+     * @param data - Datos del error a reportar
+     * @returns Resultado del reporte con hash de deduplicacion
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.errors.report({
+     *   message: 'Error al procesar pago',
+     *   module: 'pagos',
+     *   severity: 'critical',
+     *   stack: error.stack,
+     *   endpoint: '/api/payments',
+     *   method: 'POST',
+     * });
+     * console.log(result.hash); // Hash unico del error
+     * console.log(result.deduplicated); // true si ya existia
+     * ```
+     */
+    report(data: ReportErrorInput): Promise<ReportedError>;
+    /**
+     * Listar errores reportados por esta aplicacion
+     *
+     * @param filters - Filtros opcionales (severidad, modulo, paginacion)
+     * @returns Lista paginada de errores
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.errors.list({
+     *   severity: ['critical', 'high'],
+     *   resolved: false,
+     *   limit: 20,
+     * });
+     * console.log(result.data); // Array de errores
+     * ```
+     */
+    list(filters?: ErrorFilters): Promise<PaginatedResponse<SystemError>>;
+    /**
+     * Obtener estadisticas de errores de esta aplicacion
+     *
+     * @returns Estadisticas agregadas de errores
+     *
+     * @example
+     * ```typescript
+     * const stats = await sdk.errors.stats();
+     * console.log(stats.total); // Total de errores
+     * console.log(stats.unresolved); // Errores sin resolver
+     * console.log(stats.bySeverity); // { critical: 5, high: 10, ... }
+     * ```
+     */
+    stats(): Promise<ErrorStats>;
+}
+
+/**
+ * Servicio de archivos adjuntos
+ * Permite subir archivos para adjuntar a tickets
+ */
+
+declare class FilesService {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: UtiliaClient);
+    /**
+     * Subir un archivo para adjuntar a tickets
+     *
+     * @param file - Archivo a subir (File o Blob)
+     * @param options - Opciones de subida
+     * @returns Archivo subido con su ID
+     *
+     * @example Browser
+     * ```typescript
+     * // Desde input file
+     * const input = document.querySelector('input[type="file"]');
+     * const file = input.files[0];
+     * const uploaded = await sdk.files.upload(file);
+     *
+     * // Usar en ticket
+     * await sdk.tickets.create({
+     *   ...ticketData,
+     *   attachmentIds: [uploaded.id],
+     * });
+     * ```
+     */
+    upload(file: File | Blob, options?: UploadFileOptions): Promise<UploadedFile>;
+    /**
+     * Obtener URL de descarga para un archivo
+     *
+     * @param fileId - ID del archivo
+     * @returns URL temporal de descarga
+     */
+    getUrl(fileId: string): Promise<string>;
+    /**
+     * Obtener informacion de quota de almacenamiento
+     *
+     * @returns Informacion de uso y limites
+     */
+    getQuota(): Promise<FileQuota>;
+}
+
 /**
  * Servicio de tickets de soporte
  * Maneja todas las operaciones relacionadas con tickets
@@ -1019,9 +1204,12 @@ declare class UtiliaSDKError extends Error {
     readonly requestId?: string;
     /** Codigo de estado HTTP de la respuesta */
     readonly statusCode?: number;
+    /** Codigo de error de negocio especifico del backend (ej: TICKET_NOT_FOUND, FILE_INVALID_MIME) */
+    readonly errorCode?: string;
     constructor(code: ErrorCode, message: string, options?: {
         requestId?: string;
         statusCode?: number;
+        errorCode?: string;
     });
     /**
      * Serializa el error a un objeto JSON
@@ -1029,6 +1217,7 @@ declare class UtiliaSDKError extends Error {
     toJSON(): {
         name: string;
         code: ErrorCode;
+        errorCode: string | undefined;
         message: string;
         timestamp: string;
         requestId: string | undefined;
@@ -1098,12 +1287,15 @@ declare const SDK_LIMITS: {
  * Clase principal del SDK de UTILIA OS
  *
  * Proporciona acceso a todos los servicios disponibles:
+ * - `errors`: Reporte y consulta de errores del sistema
  * - `files`: Operaciones con archivos adjuntos
  * - `tickets`: Operaciones con tickets de soporte
  * - `users`: Operaciones con usuarios externos
  * - `ai`: Funcionalidades de IA (transcripcion, sugerencias)
  */
 declare class UtiliaSDK {
+    /** Servicio de errores del sistema */
+    readonly errors: ErrorsService;
     /** Servicio de archivos adjuntos */
     readonly files: FilesService;
     /** Servicio de tickets de soporte */
@@ -1139,4 +1331,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 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 };
+export { type AddMessageInput, type AiJobStatus, type AiSuggestInput, type AiSuggestions, type AiUserAction, type CreateTicketInput, type CreateTicketUser, type CreatedMessage, type CreatedTicket, ErrorCode, type ErrorFilters, type ErrorHttpMethod, type ErrorSeverity, type ErrorStats, type ExternalUser, type FileQuota, type GetSuggestionsOptions, type IdentifyUserInput, type MessageAuthor, type PaginatedResponse, type PaginationMeta, type ReportErrorInput, type ReportedError, type RequestConfig, SDK_LIMITS, type SseEvent, type StreamSuggestionsHandle, type StreamSuggestionsOptions, type StreamTranscriptionOptions, type SystemError, 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

@@ -85,6 +85,23 @@ declare class UtiliaClient {
     postForm<T>(url: string, formData: FormData, onProgress?: (progress: number) => void): Promise<T>;
 }
 
+/**
+ * Tipos comunes compartidos en el SDK
+ */
+type TicketStatus = 'OPEN' | 'IN_REVIEW' | 'RESOLVED' | 'CLOSED';
+type TicketCategory = 'CONSULTA' | 'PROBLEMA' | 'SUGERENCIA' | 'OTRO';
+type TicketPriority = 'BAJA' | 'MEDIA' | 'ALTA' | 'CRITICA';
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: PaginationMeta;
+}
+
 /**
  * Tipos relacionados con archivos adjuntos
  */
@@ -130,69 +147,6 @@ interface FileQuota {
     usagePercent: number;
 }
 
-/**
- * Servicio de archivos adjuntos
- * Permite subir archivos para adjuntar a tickets
- */
-
-declare class FilesService {
-    private readonly client;
-    private readonly basePath;
-    constructor(client: UtiliaClient);
-    /**
-     * Subir un archivo para adjuntar a tickets
-     *
-     * @param file - Archivo a subir (File o Blob)
-     * @param options - Opciones de subida
-     * @returns Archivo subido con su ID
-     *
-     * @example Browser
-     * ```typescript
-     * // Desde input file
-     * const input = document.querySelector('input[type="file"]');
-     * const file = input.files[0];
-     * const uploaded = await sdk.files.upload(file);
-     *
-     * // Usar en ticket
-     * await sdk.tickets.create({
-     *   ...ticketData,
-     *   attachmentIds: [uploaded.id],
-     * });
-     * ```
-     */
-    upload(file: File | Blob, options?: UploadFileOptions): Promise<UploadedFile>;
-    /**
-     * Obtener URL de descarga para un archivo
-     *
-     * @param fileId - ID del archivo
-     * @returns URL temporal de descarga
-     */
-    getUrl(fileId: string): Promise<string>;
-    /**
-     * Obtener informacion de quota de almacenamiento
-     *
-     * @returns Informacion de uso y limites
-     */
-    getQuota(): Promise<FileQuota>;
-}
-
-/**
- * Tipos comunes compartidos en el SDK
- */
-type TicketStatus = 'OPEN' | 'IN_REVIEW' | 'RESOLVED' | 'CLOSED';
-type TicketCategory = 'CONSULTA' | 'PROBLEMA' | 'SUGERENCIA' | 'OTRO';
-type TicketPriority = 'BAJA' | 'MEDIA' | 'ALTA' | 'CRITICA';
-interface PaginationMeta {
-    page: number;
-    limit: number;
-    total: number;
-    totalPages: number;
-}
-interface PaginatedResponse<T> {
-    data: T[];
-    pagination: PaginationMeta;
-}
-
 /**
  * Tipos relacionados con tickets de soporte
  */
@@ -410,6 +364,237 @@ interface ExternalUser {
     };
 }
 
+/**
+ * Tipos relacionados con errores del sistema
+ */
+/**
+ * Nivel de severidad de un error
+ */
+type ErrorSeverity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * Metodo HTTP asociado a un error
+ */
+type ErrorHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Datos de entrada para reportar un error
+ */
+interface ReportErrorInput {
+    /** Mensaje descriptivo del error (1-2000 caracteres) */
+    message: string;
+    /** Nivel de severidad del error */
+    severity?: ErrorSeverity;
+    /** Modulo o area donde ocurrio el error (1-100 caracteres) */
+    module: string;
+    /** Stack trace del error */
+    stack?: string;
+    /** Archivo donde ocurrio el error */
+    file?: string;
+    /** Linea del archivo donde ocurrio el error */
+    line?: number;
+    /** Funcion donde ocurrio el error */
+    function?: string;
+    /** Endpoint relacionado con el error */
+    endpoint?: string;
+    /** Metodo HTTP de la peticion que causo el error */
+    method?: ErrorHttpMethod;
+    /** ID del usuario afectado */
+    userId?: string;
+    /** ID de la peticion donde ocurrio el error */
+    requestId?: string;
+    /** Contexto adicional del error */
+    context?: Record<string, unknown>;
+}
+/**
+ * Respuesta al reportar un error
+ */
+interface ReportedError {
+    /** Indica si el error fue registrado correctamente */
+    success: boolean;
+    /** Hash unico del error (para deduplicacion) */
+    hash: string;
+    /** Indica si el error ya existia y se incremento su contador */
+    deduplicated: boolean;
+}
+/**
+ * Error del sistema en listados
+ */
+interface SystemError {
+    /** ID unico del error */
+    id: string;
+    /** Hash de deduplicacion */
+    hash: string;
+    /** Mensaje del error */
+    message: string;
+    /** Modulo donde ocurrio */
+    module: string;
+    /** Nivel de severidad */
+    severity: ErrorSeverity;
+    /** Archivo donde ocurrio */
+    file?: string;
+    /** Linea del archivo */
+    line?: number;
+    /** Endpoint relacionado */
+    endpoint?: string;
+    /** Numero de ocurrencias */
+    count: number;
+    /** Fecha de la primera ocurrencia */
+    firstOccurrence: string;
+    /** Fecha de la ultima ocurrencia */
+    lastOccurrence: string;
+    /** Indica si el error esta resuelto */
+    resolved: boolean;
+    /** Fecha en que se resolvio */
+    resolvedAt?: string;
+}
+/**
+ * Filtros para listar errores
+ */
+interface ErrorFilters {
+    /** Filtrar por niveles de severidad */
+    severity?: ErrorSeverity[];
+    /** Filtrar por modulo */
+    module?: string;
+    /** Filtrar por estado de resolucion */
+    resolved?: boolean;
+    /** Numero maximo de resultados (default: 50, max: 200) */
+    limit?: number;
+    /** Desplazamiento para paginacion */
+    offset?: number;
+    /** Fecha de inicio (ISO 8601) */
+    from?: string;
+    /** Fecha de fin (ISO 8601) */
+    to?: string;
+}
+/**
+ * Estadisticas de errores
+ */
+interface ErrorStats {
+    /** Total de errores registrados */
+    total: number;
+    /** Errores sin resolver */
+    unresolved: number;
+    /** Distribucion por severidad */
+    bySeverity: Record<string, number>;
+    /** Distribucion por modulo */
+    byModule: Record<string, number>;
+    /** Errores mas frecuentes */
+    topErrors: Array<{
+        hash: string;
+        message: string;
+        count: number;
+        severity: string;
+    }>;
+}
+
+/**
+ * Servicio de errores del sistema
+ * Maneja todas las operaciones relacionadas con el reporte y consulta de errores
+ */
+
+declare class ErrorsService {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: UtiliaClient);
+    /**
+     * Reportar un error del sistema
+     *
+     * @param data - Datos del error a reportar
+     * @returns Resultado del reporte con hash de deduplicacion
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.errors.report({
+     *   message: 'Error al procesar pago',
+     *   module: 'pagos',
+     *   severity: 'critical',
+     *   stack: error.stack,
+     *   endpoint: '/api/payments',
+     *   method: 'POST',
+     * });
+     * console.log(result.hash); // Hash unico del error
+     * console.log(result.deduplicated); // true si ya existia
+     * ```
+     */
+    report(data: ReportErrorInput): Promise<ReportedError>;
+    /**
+     * Listar errores reportados por esta aplicacion
+     *
+     * @param filters - Filtros opcionales (severidad, modulo, paginacion)
+     * @returns Lista paginada de errores
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.errors.list({
+     *   severity: ['critical', 'high'],
+     *   resolved: false,
+     *   limit: 20,
+     * });
+     * console.log(result.data); // Array de errores
+     * ```
+     */
+    list(filters?: ErrorFilters): Promise<PaginatedResponse<SystemError>>;
+    /**
+     * Obtener estadisticas de errores de esta aplicacion
+     *
+     * @returns Estadisticas agregadas de errores
+     *
+     * @example
+     * ```typescript
+     * const stats = await sdk.errors.stats();
+     * console.log(stats.total); // Total de errores
+     * console.log(stats.unresolved); // Errores sin resolver
+     * console.log(stats.bySeverity); // { critical: 5, high: 10, ... }
+     * ```
+     */
+    stats(): Promise<ErrorStats>;
+}
+
+/**
+ * Servicio de archivos adjuntos
+ * Permite subir archivos para adjuntar a tickets
+ */
+
+declare class FilesService {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: UtiliaClient);
+    /**
+     * Subir un archivo para adjuntar a tickets
+     *
+     * @param file - Archivo a subir (File o Blob)
+     * @param options - Opciones de subida
+     * @returns Archivo subido con su ID
+     *
+     * @example Browser
+     * ```typescript
+     * // Desde input file
+     * const input = document.querySelector('input[type="file"]');
+     * const file = input.files[0];
+     * const uploaded = await sdk.files.upload(file);
+     *
+     * // Usar en ticket
+     * await sdk.tickets.create({
+     *   ...ticketData,
+     *   attachmentIds: [uploaded.id],
+     * });
+     * ```
+     */
+    upload(file: File | Blob, options?: UploadFileOptions): Promise<UploadedFile>;
+    /**
+     * Obtener URL de descarga para un archivo
+     *
+     * @param fileId - ID del archivo
+     * @returns URL temporal de descarga
+     */
+    getUrl(fileId: string): Promise<string>;
+    /**
+     * Obtener informacion de quota de almacenamiento
+     *
+     * @returns Informacion de uso y limites
+     */
+    getQuota(): Promise<FileQuota>;
+}
+
 /**
  * Servicio de tickets de soporte
  * Maneja todas las operaciones relacionadas con tickets
@@ -1019,9 +1204,12 @@ declare class UtiliaSDKError extends Error {
     readonly requestId?: string;
     /** Codigo de estado HTTP de la respuesta */
     readonly statusCode?: number;
+    /** Codigo de error de negocio especifico del backend (ej: TICKET_NOT_FOUND, FILE_INVALID_MIME) */
+    readonly errorCode?: string;
     constructor(code: ErrorCode, message: string, options?: {
         requestId?: string;
         statusCode?: number;
+        errorCode?: string;
     });
     /**
      * Serializa el error a un objeto JSON
@@ -1029,6 +1217,7 @@ declare class UtiliaSDKError extends Error {
     toJSON(): {
         name: string;
         code: ErrorCode;
+        errorCode: string | undefined;
         message: string;
         timestamp: string;
         requestId: string | undefined;
@@ -1098,12 +1287,15 @@ declare const SDK_LIMITS: {
  * Clase principal del SDK de UTILIA OS
  *
  * Proporciona acceso a todos los servicios disponibles:
+ * - `errors`: Reporte y consulta de errores del sistema
  * - `files`: Operaciones con archivos adjuntos
  * - `tickets`: Operaciones con tickets de soporte
  * - `users`: Operaciones con usuarios externos
  * - `ai`: Funcionalidades de IA (transcripcion, sugerencias)
  */
 declare class UtiliaSDK {
+    /** Servicio de errores del sistema */
+    readonly errors: ErrorsService;
     /** Servicio de archivos adjuntos */
     readonly files: FilesService;
     /** Servicio de tickets de soporte */
@@ -1139,4 +1331,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 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 };
+export { type AddMessageInput, type AiJobStatus, type AiSuggestInput, type AiSuggestions, type AiUserAction, type CreateTicketInput, type CreateTicketUser, type CreatedMessage, type CreatedTicket, ErrorCode, type ErrorFilters, type ErrorHttpMethod, type ErrorSeverity, type ErrorStats, type ExternalUser, type FileQuota, type GetSuggestionsOptions, type IdentifyUserInput, type MessageAuthor, type PaginatedResponse, type PaginationMeta, type ReportErrorInput, type ReportedError, type RequestConfig, SDK_LIMITS, type SseEvent, type StreamSuggestionsHandle, type StreamSuggestionsOptions, type StreamTranscriptionOptions, type SystemError, 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

@@ -59,6 +59,7 @@ var UtiliaSDKError = class _UtiliaSDKError extends Error {
     this.timestamp = /* @__PURE__ */ new Date();
     this.requestId = options?.requestId;
     this.statusCode = options?.statusCode;
+    this.errorCode = options?.errorCode;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _UtiliaSDKError);
     }
@@ -70,6 +71,7 @@ var UtiliaSDKError = class _UtiliaSDKError extends Error {
     return {
       name: this.name,
       code: this.code,
+      errorCode: this.errorCode,
       message: this.message,
       timestamp: this.timestamp.toISOString(),
       requestId: this.requestId,
@@ -146,7 +148,9 @@ var UtiliaClient = class {
   toSDKError(error) {
     const requestId = error.response?.headers?.["x-request-id"] || error.config?._requestId;
     const statusCode = error.response?.status;
-    const errorOptions = { requestId, statusCode };
+    const data = error.response?.data;
+    const errorCode = data?.errorCode;
+    const errorOptions = { requestId, statusCode, errorCode };
     if (!error.response) {
       if (error.code === "ECONNABORTED") {
         return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Timeout: la solicitud excedio el tiempo limite", errorOptions);
@@ -154,7 +158,6 @@ var UtiliaClient = class {
       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:
@@ -317,18 +320,6 @@ var UtiliaClient = class {
   }
 };
 
-// src/constants.ts
-var SDK_LIMITS = {
-  TICKET_TITLE_MIN: 5,
-  TICKET_TITLE_MAX: 500,
-  TICKET_DESCRIPTION_MIN: 10,
-  MESSAGE_CONTENT_MIN: 1,
-  MESSAGE_CONTENT_MAX: 5e3,
-  FILE_NAME_MAX: 255,
-  EXTERNAL_ID_MAX: 255,
-  AVATAR_URL_MAX: 2048
-};
-
 // src/utils/validators.ts
 function validateEmail(email) {
   const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -371,6 +362,88 @@ function validateRequired(value, fieldName) {
   }
 }
 
+// src/services/errors.service.ts
+var ErrorsService = class {
+  constructor(client) {
+    this.basePath = "/external/v1/errors";
+    this.client = client;
+  }
+  /**
+   * Reportar un error del sistema
+   *
+   * @param data - Datos del error a reportar
+   * @returns Resultado del reporte con hash de deduplicacion
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.errors.report({
+   *   message: 'Error al procesar pago',
+   *   module: 'pagos',
+   *   severity: 'critical',
+   *   stack: error.stack,
+   *   endpoint: '/api/payments',
+   *   method: 'POST',
+   * });
+   * console.log(result.hash); // Hash unico del error
+   * console.log(result.deduplicated); // true si ya existia
+   * ```
+   */
+  async report(data) {
+    validateRequired(data.message, "message");
+    validateRequired(data.module, "module");
+    return this.client.post(`${this.basePath}/report`, data);
+  }
+  /**
+   * Listar errores reportados por esta aplicacion
+   *
+   * @param filters - Filtros opcionales (severidad, modulo, paginacion)
+   * @returns Lista paginada de errores
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.errors.list({
+   *   severity: ['critical', 'high'],
+   *   resolved: false,
+   *   limit: 20,
+   * });
+   * console.log(result.data); // Array de errores
+   * ```
+   */
+  async list(filters) {
+    return this.client.get(this.basePath, {
+      params: filters ? { ...filters } : void 0
+    });
+  }
+  /**
+   * Obtener estadisticas de errores de esta aplicacion
+   *
+   * @returns Estadisticas agregadas de errores
+   *
+   * @example
+   * ```typescript
+   * const stats = await sdk.errors.stats();
+   * console.log(stats.total); // Total de errores
+   * console.log(stats.unresolved); // Errores sin resolver
+   * console.log(stats.bySeverity); // { critical: 5, high: 10, ... }
+   * ```
+   */
+  async stats() {
+    return this.client.get(`${this.basePath}/stats`);
+  }
+};
+
+// src/constants.ts
+var SDK_LIMITS = {
+  TICKET_TITLE_MIN: 5,
+  TICKET_TITLE_MAX: 500,
+  TICKET_DESCRIPTION_MIN: 10,
+  MESSAGE_CONTENT_MIN: 1,
+  MESSAGE_CONTENT_MAX: 5e3,
+  FILE_NAME_MAX: 255,
+  EXTERNAL_ID_MAX: 255,
+  AVATAR_URL_MAX: 2048
+};
+
 // src/services/files.service.ts
 var FilesService = class {
   constructor(client) {
@@ -1090,6 +1163,7 @@ var UtiliaSDK = class {
    */
   constructor(config) {
     const client = new UtiliaClient(config);
+    this.errors = new ErrorsService(client);
     this.files = new FilesService(client);
     this.tickets = new TicketsService(client);
     this.users = new UsersService(client);

package/dist/index.mjs

@@ -20,6 +20,7 @@ var UtiliaSDKError = class _UtiliaSDKError extends Error {
     this.timestamp = /* @__PURE__ */ new Date();
     this.requestId = options?.requestId;
     this.statusCode = options?.statusCode;
+    this.errorCode = options?.errorCode;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _UtiliaSDKError);
     }
@@ -31,6 +32,7 @@ var UtiliaSDKError = class _UtiliaSDKError extends Error {
     return {
       name: this.name,
       code: this.code,
+      errorCode: this.errorCode,
       message: this.message,
       timestamp: this.timestamp.toISOString(),
       requestId: this.requestId,
@@ -107,7 +109,9 @@ var UtiliaClient = class {
   toSDKError(error) {
     const requestId = error.response?.headers?.["x-request-id"] || error.config?._requestId;
     const statusCode = error.response?.status;
-    const errorOptions = { requestId, statusCode };
+    const data = error.response?.data;
+    const errorCode = data?.errorCode;
+    const errorOptions = { requestId, statusCode, errorCode };
     if (!error.response) {
       if (error.code === "ECONNABORTED") {
         return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Timeout: la solicitud excedio el tiempo limite", errorOptions);
@@ -115,7 +119,6 @@ var UtiliaClient = class {
       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:
@@ -278,18 +281,6 @@ var UtiliaClient = class {
   }
 };
 
-// src/constants.ts
-var SDK_LIMITS = {
-  TICKET_TITLE_MIN: 5,
-  TICKET_TITLE_MAX: 500,
-  TICKET_DESCRIPTION_MIN: 10,
-  MESSAGE_CONTENT_MIN: 1,
-  MESSAGE_CONTENT_MAX: 5e3,
-  FILE_NAME_MAX: 255,
-  EXTERNAL_ID_MAX: 255,
-  AVATAR_URL_MAX: 2048
-};
-
 // src/utils/validators.ts
 function validateEmail(email) {
   const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -332,6 +323,88 @@ function validateRequired(value, fieldName) {
   }
 }
 
+// src/services/errors.service.ts
+var ErrorsService = class {
+  constructor(client) {
+    this.basePath = "/external/v1/errors";
+    this.client = client;
+  }
+  /**
+   * Reportar un error del sistema
+   *
+   * @param data - Datos del error a reportar
+   * @returns Resultado del reporte con hash de deduplicacion
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.errors.report({
+   *   message: 'Error al procesar pago',
+   *   module: 'pagos',
+   *   severity: 'critical',
+   *   stack: error.stack,
+   *   endpoint: '/api/payments',
+   *   method: 'POST',
+   * });
+   * console.log(result.hash); // Hash unico del error
+   * console.log(result.deduplicated); // true si ya existia
+   * ```
+   */
+  async report(data) {
+    validateRequired(data.message, "message");
+    validateRequired(data.module, "module");
+    return this.client.post(`${this.basePath}/report`, data);
+  }
+  /**
+   * Listar errores reportados por esta aplicacion
+   *
+   * @param filters - Filtros opcionales (severidad, modulo, paginacion)
+   * @returns Lista paginada de errores
+   *
+   * @example
+   * ```typescript
+   * const result = await sdk.errors.list({
+   *   severity: ['critical', 'high'],
+   *   resolved: false,
+   *   limit: 20,
+   * });
+   * console.log(result.data); // Array de errores
+   * ```
+   */
+  async list(filters) {
+    return this.client.get(this.basePath, {
+      params: filters ? { ...filters } : void 0
+    });
+  }
+  /**
+   * Obtener estadisticas de errores de esta aplicacion
+   *
+   * @returns Estadisticas agregadas de errores
+   *
+   * @example
+   * ```typescript
+   * const stats = await sdk.errors.stats();
+   * console.log(stats.total); // Total de errores
+   * console.log(stats.unresolved); // Errores sin resolver
+   * console.log(stats.bySeverity); // { critical: 5, high: 10, ... }
+   * ```
+   */
+  async stats() {
+    return this.client.get(`${this.basePath}/stats`);
+  }
+};
+
+// src/constants.ts
+var SDK_LIMITS = {
+  TICKET_TITLE_MIN: 5,
+  TICKET_TITLE_MAX: 500,
+  TICKET_DESCRIPTION_MIN: 10,
+  MESSAGE_CONTENT_MIN: 1,
+  MESSAGE_CONTENT_MAX: 5e3,
+  FILE_NAME_MAX: 255,
+  EXTERNAL_ID_MAX: 255,
+  AVATAR_URL_MAX: 2048
+};
+
 // src/services/files.service.ts
 var FilesService = class {
   constructor(client) {
@@ -1051,6 +1124,7 @@ var UtiliaSDK = class {
    */
   constructor(config) {
     const client = new UtiliaClient(config);
+    this.errors = new ErrorsService(client);
     this.files = new FilesService(client);
     this.tickets = new TicketsService(client);
     this.users = new UsersService(client);

package/package.json

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