@utilia-os/sdk-js 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,872 @@
+/**
+ * Tipos de configuracion del SDK
+ */
+interface UtiliaSDKConfig {
+    /** URL base de la API (ej: https://os.utilia.ai/api) */
+    baseURL: string;
+    /** API Key para autenticacion */
+    apiKey: string;
+    /** Timeout en milisegundos (default: 30000) */
+    timeout?: number;
+    /** Numero de reintentos en caso de error (default: 3) */
+    retryAttempts?: number;
+    /** Habilitar logs de debug (default: false) */
+    debug?: boolean;
+}
+interface RequestConfig {
+    headers?: Record<string, string>;
+    params?: Record<string, unknown>;
+}
+
+/**
+ * Cliente HTTP base para el SDK
+ * Maneja la comunicacion con la API de UTILIA OS
+ */
+
+declare class UtiliaClient {
+    private readonly axios;
+    private readonly config;
+    constructor(config: UtiliaSDKConfig);
+    /**
+     * Configura los interceptores de request y response
+     */
+    private setupInterceptors;
+    /**
+     * Convierte un error de Axios en un UtiliaSDKError
+     */
+    private toSDKError;
+    /**
+     * Determina si un error es recuperable y se debe reintentar
+     */
+    private isRetryableError;
+    /**
+     * Ejecuta una funcion con reintentos y backoff exponencial
+     */
+    private executeWithRetry;
+    /**
+     * Helper para esperar un tiempo
+     */
+    private sleep;
+    /**
+     * Realiza una peticion GET
+     */
+    get<T>(url: string, config?: RequestConfig): Promise<T>;
+    /**
+     * Realiza una peticion POST
+     */
+    post<T>(url: string, data?: unknown, config?: RequestConfig): Promise<T>;
+    /**
+     * Realiza una peticion PATCH
+     */
+    patch<T>(url: string, data?: unknown, config?: RequestConfig): Promise<T>;
+    /**
+     * Realiza una peticion PUT
+     */
+    put<T>(url: string, data?: unknown, config?: RequestConfig): Promise<T>;
+    /**
+     * Realiza una peticion DELETE
+     */
+    delete<T>(url: string, config?: RequestConfig): Promise<T>;
+    /**
+     * Realiza una peticion POST con FormData (para subir archivos)
+     */
+    postForm<T>(url: string, formData: FormData, onProgress?: (progress: number) => void): Promise<T>;
+}
+
+/**
+ * Tipos relacionados con archivos adjuntos
+ */
+/**
+ * Opciones para subir un archivo
+ */
+interface UploadFileOptions {
+    /** Nombre personalizado para el archivo (opcional) */
+    name?: string;
+    /** Metadatos adicionales (opcional) */
+    metadata?: Record<string, unknown>;
+    /** Callback de progreso (opcional) */
+    onProgress?: (progress: number) => void;
+}
+/**
+ * Respuesta al subir un archivo
+ */
+interface UploadedFile {
+    /** ID del archivo para usar en attachmentIds */
+    id: string;
+    /** Nombre original del archivo */
+    originalName: string;
+    /** Tipo MIME */
+    mimeType: string;
+    /** Tamano en bytes */
+    size: number;
+    /** URL temporal de descarga */
+    downloadUrl: string;
+    /** Fecha de creacion */
+    createdAt: string;
+}
+/**
+ * Informacion de quota de almacenamiento
+ */
+interface FileQuota {
+    /** Bytes usados */
+    usedBytes: number;
+    /** Bytes maximos permitidos */
+    maxBytes: number;
+    /** Tamano maximo por archivo */
+    maxFileSizeBytes: number;
+    /** Porcentaje de uso (0-100) */
+    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
+ */
+
+/**
+ * Datos del usuario para crear ticket
+ */
+interface CreateTicketUser {
+    /** ID unico del usuario en tu sistema */
+    externalId: string;
+    /** Email del usuario (opcional) */
+    email?: string;
+    /** Nombre del usuario (opcional) */
+    name?: string;
+    /** Metadatos adicionales del usuario (opcional) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Contexto adicional del ticket
+ */
+interface TicketContext {
+    /** URL donde se origino el ticket */
+    url?: string;
+    /** Version de la aplicacion */
+    appVersion?: string;
+    /** Informacion del navegador */
+    browserInfo?: string;
+    /** Datos personalizados adicionales */
+    customData?: Record<string, unknown>;
+}
+/**
+ * DTO para crear un nuevo ticket
+ */
+interface CreateTicketInput {
+    /** Datos del usuario que crea el ticket */
+    user: CreateTicketUser;
+    /** Titulo del ticket (5-500 caracteres) */
+    title: string;
+    /** Descripcion detallada (minimo 10 caracteres) */
+    description: string;
+    /** Categoria del ticket */
+    category?: TicketCategory;
+    /** Prioridad del ticket */
+    priority?: TicketPriority;
+    /** Contexto adicional */
+    context?: TicketContext;
+    /** IDs de archivos adjuntos (previamente subidos) */
+    attachmentIds?: string[];
+}
+/**
+ * Filtros para listar tickets
+ */
+interface TicketFilters {
+    /** Filtrar por estado */
+    status?: TicketStatus;
+    /** Pagina actual (default: 1) */
+    page?: number;
+    /** Elementos por pagina (default: 20, max: 100) */
+    limit?: number;
+}
+/**
+ * DTO para agregar un mensaje a un ticket
+ */
+interface AddMessageInput {
+    /** Contenido del mensaje (1-5000 caracteres) */
+    content: string;
+    /** IDs de archivos adjuntos (opcional) */
+    attachmentIds?: string[];
+}
+/**
+ * Respuesta al crear un ticket
+ */
+interface CreatedTicket {
+    /** ID interno del ticket */
+    id: string;
+    /** Clave unica del ticket (ej: APP-0001) */
+    ticketKey: string;
+    /** Titulo del ticket */
+    title: string;
+    /** Estado inicial */
+    status: TicketStatus;
+    /** Fecha de creacion */
+    createdAt: string;
+}
+/**
+ * Ticket en listado (version resumida)
+ */
+interface TicketListItem {
+    id: string;
+    ticketKey: string;
+    title: string;
+    category: TicketCategory;
+    priority: TicketPriority;
+    status: TicketStatus;
+    /** Numero de mensajes no leidos por el usuario externo */
+    unreadByExternal: number;
+    createdAt: string;
+    lastActivityAt: string;
+}
+/**
+ * Autor de un mensaje
+ */
+interface MessageAuthor {
+    /** Tipo de autor */
+    type: 'EXTERNAL' | 'INTERNAL';
+    /** ID del autor (externalId o nombre de agente) */
+    id: string;
+    /** Nombre visible del autor */
+    name: string;
+}
+/**
+ * Archivo adjunto
+ */
+interface TicketAttachment {
+    id: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+}
+/**
+ * Mensaje de un ticket
+ */
+interface TicketMessage {
+    id: string;
+    content: string;
+    author: MessageAuthor;
+    attachments: TicketAttachment[];
+    createdAt: string;
+}
+/**
+ * Detalle completo de un ticket
+ */
+interface TicketDetail {
+    id: string;
+    ticketKey: string;
+    title: string;
+    description: string;
+    category: TicketCategory;
+    priority: TicketPriority;
+    status: TicketStatus;
+    createdAt: string;
+    lastActivityAt: string;
+    /** Lista de mensajes del ticket */
+    messages: TicketMessage[];
+    /** Archivos adjuntos del ticket original */
+    attachments: TicketAttachment[];
+}
+/**
+ * Respuesta al crear un mensaje
+ */
+interface CreatedMessage {
+    id: string;
+    content: string;
+    createdAt: string;
+}
+/**
+ * Conteo de mensajes no leidos
+ */
+interface UnreadCount {
+    count: number;
+}
+
+/**
+ * Tipos relacionados con usuarios externos
+ */
+/**
+ * DTO para identificar/actualizar un usuario externo
+ */
+interface IdentifyUserInput {
+    /** ID unico del usuario en tu sistema (requerido) */
+    externalId: string;
+    /** Email del usuario */
+    email?: string;
+    /** Nombre del usuario */
+    name?: string;
+    /** URL del avatar del usuario */
+    avatarUrl?: string;
+    /** Metadatos adicionales del usuario */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Usuario externo registrado
+ */
+interface ExternalUser {
+    /** ID interno en UTILIA OS */
+    id: string;
+    /** ID de la aplicacion externa */
+    appId: string;
+    /** ID del usuario en el sistema externo */
+    externalId: string;
+    /** Email del usuario */
+    email?: string | null;
+    /** Nombre del usuario */
+    name?: string | null;
+    /** URL del avatar */
+    avatarUrl?: string | null;
+    /** Metadatos adicionales */
+    metadata?: Record<string, unknown> | null;
+    /** Ultima vez que el usuario estuvo activo */
+    lastSeenAt: string;
+    /** Contadores relacionados */
+    _count?: {
+        tickets: number;
+    };
+}
+
+/**
+ * Servicio de tickets de soporte
+ * Maneja todas las operaciones relacionadas con tickets
+ */
+
+declare class TicketsService {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: UtiliaClient);
+    /**
+     * Crear un nuevo ticket de soporte
+     *
+     * @param data - Datos del ticket a crear
+     * @returns Ticket creado con su ID y clave unica
+     *
+     * @example
+     * ```typescript
+     * const ticket = await sdk.tickets.create({
+     *   user: { externalId: 'user-123', email: 'user@example.com' },
+     *   title: 'Problema con facturacion',
+     *   description: 'No puedo ver mis facturas del mes pasado...',
+     *   category: 'PROBLEMA',
+     *   priority: 'MEDIA',
+     * });
+     * console.log(ticket.ticketKey); // APP-0001
+     * ```
+     */
+    create(data: CreateTicketInput): Promise<CreatedTicket>;
+    /**
+     * Listar tickets de un usuario
+     *
+     * @param userId - ID externo del usuario
+     * @param filters - Filtros opcionales (status, paginacion)
+     * @returns Lista paginada de tickets
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.tickets.list('user-123', {
+     *   status: 'OPEN',
+     *   page: 1,
+     *   limit: 10,
+     * });
+     * console.log(result.data); // Array de tickets
+     * console.log(result.pagination.total); // Total de tickets
+     * ```
+     */
+    list(userId: string, filters?: TicketFilters): Promise<PaginatedResponse<TicketListItem>>;
+    /**
+     * Obtener detalle completo de un ticket
+     * Incluye todos los mensajes y adjuntos
+     *
+     * @param ticketId - ID del ticket
+     * @param userId - ID externo del usuario (para verificar acceso)
+     * @returns Detalle del ticket con mensajes
+     *
+     * @example
+     * ```typescript
+     * const ticket = await sdk.tickets.get('ticket-uuid', 'user-123');
+     * console.log(ticket.messages); // Array de mensajes
+     * ```
+     */
+    get(ticketId: string, userId: string): Promise<TicketDetail>;
+    /**
+     * Obtener conteo de mensajes no leidos para un usuario
+     *
+     * @param userId - ID externo del usuario
+     * @returns Numero de mensajes no leidos
+     *
+     * @example
+     * ```typescript
+     * const { count } = await sdk.tickets.getUnreadCount('user-123');
+     * if (count > 0) {
+     *   console.log(`Tienes ${count} mensajes sin leer`);
+     * }
+     * ```
+     */
+    getUnreadCount(userId: string): Promise<UnreadCount>;
+    /**
+     * Agregar un mensaje a un ticket existente
+     *
+     * @param ticketId - ID del ticket
+     * @param userId - ID externo del usuario
+     * @param data - Contenido del mensaje
+     * @returns Mensaje creado
+     *
+     * @example
+     * ```typescript
+     * const message = await sdk.tickets.addMessage('ticket-uuid', 'user-123', {
+     *   content: 'Gracias por la respuesta, el problema ya fue resuelto.',
+     * });
+     * ```
+     */
+    addMessage(ticketId: string, userId: string, data: AddMessageInput): Promise<CreatedMessage>;
+    /**
+     * Cerrar un ticket
+     * Solo el usuario que creo el ticket puede cerrarlo
+     *
+     * @param ticketId - ID del ticket
+     * @param userId - ID externo del usuario
+     *
+     * @example
+     * ```typescript
+     * await sdk.tickets.close('ticket-uuid', 'user-123');
+     * ```
+     */
+    close(ticketId: string, userId: string): Promise<void>;
+    /**
+     * Reabrir un ticket cerrado
+     * Solo el usuario que creo el ticket puede reabrirlo
+     *
+     * @param ticketId - ID del ticket
+     * @param userId - ID externo del usuario
+     *
+     * @example
+     * ```typescript
+     * await sdk.tickets.reopen('ticket-uuid', 'user-123');
+     * ```
+     */
+    reopen(ticketId: string, userId: string): Promise<void>;
+}
+
+/**
+ * Servicio de usuarios externos
+ * Maneja las operaciones relacionadas con usuarios
+ */
+
+declare class UsersService {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: UtiliaClient);
+    /**
+     * Identificar o actualizar un usuario externo
+     * Si el usuario ya existe, actualiza sus datos
+     * Si no existe, lo crea
+     *
+     * @param data - Datos del usuario
+     * @returns Usuario creado o actualizado
+     *
+     * @example
+     * ```typescript
+     * const user = await sdk.users.identify({
+     *   externalId: 'user-123',
+     *   email: 'user@example.com',
+     *   name: 'Juan Perez',
+     *   metadata: {
+     *     plan: 'premium',
+     *     company: 'Acme Inc',
+     *   },
+     * });
+     * console.log(user.id); // ID interno en UTILIA OS
+     * ```
+     */
+    identify(data: IdentifyUserInput): Promise<ExternalUser>;
+    /**
+     * Listar usuarios de la aplicacion
+     *
+     * @param page - Pagina actual (default: 1)
+     * @param limit - Elementos por pagina (default: 20)
+     * @returns Lista paginada de usuarios
+     *
+     * @example
+     * ```typescript
+     * const result = await sdk.users.list(1, 50);
+     * console.log(result.data); // Array de usuarios
+     * console.log(result.pagination.total); // Total de usuarios
+     * ```
+     */
+    list(page?: number, limit?: number): Promise<PaginatedResponse<ExternalUser>>;
+}
+
+/**
+ * Servicio de IA para el SDK de UTILIA OS
+ * Proporciona funcionalidades de transcripcion y sugerencias inteligentes
+ */
+
+/**
+ * Entrada para solicitar sugerencias de IA
+ */
+interface AiSuggestInput {
+    /** ID externo del usuario */
+    userId: string;
+    /** Texto del problema a analizar (opcional si se envia audio) */
+    text?: string;
+    /** Audio en base64 para transcribir (webm/mp4/mp3/wav) */
+    audioBase64?: string;
+    /** Nombre del archivo de audio con extension */
+    audioFilename?: string;
+    /** Campos existentes del formulario para contexto */
+    existingFields?: {
+        title?: string;
+        description?: string;
+        category?: string;
+        priority?: string;
+    };
+}
+/**
+ * Sugerencias generadas por IA
+ */
+interface AiSuggestions {
+    /** Titulo sugerido para el ticket */
+    title?: string | null;
+    /** Descripcion sugerida */
+    description?: string | null;
+    /** Categoria sugerida (BUG, CONSULTA, SUGERENCIA) */
+    category?: string | null;
+    /** Prioridad sugerida (BAJA, MEDIA, ALTA, CRITICA) */
+    priority?: string | null;
+}
+/**
+ * Estado del job de IA
+ */
+interface AiJobStatus {
+    /** Estado actual del job */
+    status: 'pending' | 'processing' | 'completed' | 'failed' | 'not_found';
+    /** Progreso del job (0-100) */
+    progress?: number;
+    /** Resultado del job (disponible cuando status es 'completed') */
+    result?: {
+        /** Transcripcion del audio (si se envio audio) */
+        transcription?: string;
+        /** Sugerencias generadas */
+        suggestions?: AiSuggestions;
+    };
+    /** Mensaje de error (si status es 'failed') */
+    error?: string;
+}
+/**
+ * Opciones para el metodo getSuggestions con polling
+ */
+interface GetSuggestionsOptions {
+    /** Intervalo de polling en ms (default: 1000) */
+    pollInterval?: number;
+    /** Tiempo maximo de espera en ms (default: 60000) */
+    maxWait?: number;
+    /** Callback para reportar progreso */
+    onProgress?: (progress: number) => void;
+}
+declare class AiService {
+    private readonly client;
+    private readonly basePath;
+    constructor(client: UtiliaClient);
+    /**
+     * Solicita sugerencias de IA de forma asincrona.
+     * Retorna un jobId que se puede usar para consultar el estado.
+     *
+     * @param data - Datos para generar sugerencias
+     * @returns ID del job para consultar estado
+     *
+     * @example
+     * ```typescript
+     * // Con texto
+     * const { jobId } = await sdk.ai.requestSuggestions({
+     *   userId: 'user-123',
+     *   text: 'No puedo iniciar sesion en la aplicacion',
+     * });
+     *
+     * // Con audio
+     * const { jobId } = await sdk.ai.requestSuggestions({
+     *   userId: 'user-123',
+     *   audioBase64: '...',
+     *   audioFilename: 'recording.webm',
+     * });
+     * ```
+     */
+    requestSuggestions(data: AiSuggestInput): Promise<{
+        jobId: string;
+    }>;
+    /**
+     * Obtiene el estado de un job de sugerencias
+     *
+     * @param jobId - ID del job obtenido de requestSuggestions
+     * @returns Estado actual del job
+     *
+     * @example
+     * ```typescript
+     * const status = await sdk.ai.getSuggestionsStatus(jobId);
+     *
+     * if (status.status === 'completed') {
+     *   console.log(status.result?.suggestions);
+     * }
+     * ```
+     */
+    getSuggestionsStatus(jobId: string): Promise<AiJobStatus>;
+    /**
+     * Transcribe audio a texto de forma sincrona.
+     * Usar solo para audios cortos (<30 segundos).
+     *
+     * @param audioBase64 - Audio codificado en base64
+     * @param audioFilename - Nombre del archivo con extension
+     * @returns Texto transcrito
+     *
+     * @example
+     * ```typescript
+     * const { transcription } = await sdk.ai.transcribe(
+     *   audioBase64,
+     *   'recording.webm'
+     * );
+     * console.log(transcription);
+     * ```
+     */
+    transcribe(audioBase64: string, audioFilename: string): Promise<{
+        transcription: string;
+    }>;
+    /**
+     * Metodo helper que solicita sugerencias y espera el resultado.
+     * Implementa polling automatico hasta que el job complete o falle.
+     *
+     * @param data - Datos para generar sugerencias
+     * @param options - Opciones de polling
+     * @returns Resultado con sugerencias y transcripcion (si aplica)
+     * @throws Error si el job falla o excede el timeout
+     *
+     * @example
+     * ```typescript
+     * // Uso simple
+     * const result = await sdk.ai.getSuggestions({
+     *   userId: 'user-123',
+     *   text: 'No puedo ver mis facturas del mes pasado',
+     * });
+     * console.log(result?.suggestions);
+     *
+     * // Con progreso
+     * const result = await sdk.ai.getSuggestions(
+     *   { userId: 'user-123', audioBase64: '...', audioFilename: 'rec.webm' },
+     *   {
+     *     pollInterval: 500,
+     *     maxWait: 30000,
+     *     onProgress: (p) => console.log(`Progreso: ${p}%`),
+     *   }
+     * );
+     * ```
+     */
+    getSuggestions(data: AiSuggestInput, options?: GetSuggestionsOptions): Promise<AiJobStatus['result']>;
+    /**
+     * Helper para esperar un tiempo
+     */
+    private sleep;
+}
+
+/**
+ * Codigos de error del SDK
+ */
+declare enum ErrorCode {
+    /** API Key invalida o faltante */
+    UNAUTHORIZED = "UNAUTHORIZED",
+    /** Acceso denegado (app desactivada, CORS, etc) */
+    FORBIDDEN = "FORBIDDEN",
+    /** Recurso no encontrado */
+    NOT_FOUND = "NOT_FOUND",
+    /** Rate limit excedido */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** Error de validacion en los datos enviados */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** Error de conexion de red */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Error desconocido */
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Clase de error personalizada del SDK
+ * Permite identificar el tipo de error y tomar acciones apropiadas
+ */
+declare class UtiliaSDKError extends Error {
+    /** Codigo del error para identificar el tipo */
+    readonly code: ErrorCode;
+    /** Timestamp de cuando ocurrio el error */
+    readonly timestamp: Date;
+    constructor(code: ErrorCode, message: string);
+    /**
+     * Serializa el error a un objeto JSON
+     */
+    toJSON(): {
+        name: string;
+        code: ErrorCode;
+        message: string;
+        timestamp: string;
+    };
+    /**
+     * Verifica si el error es de tipo rate limit
+     */
+    isRateLimited(): boolean;
+    /**
+     * Verifica si el error es de autenticacion
+     */
+    isUnauthorized(): boolean;
+    /**
+     * Verifica si el error es recuperable (se puede reintentar)
+     */
+    isRetryable(): boolean;
+}
+
+/**
+ * Constantes y limites del SDK
+ */
+declare const SDK_LIMITS: {
+    readonly TICKET_TITLE_MIN: 5;
+    readonly TICKET_TITLE_MAX: 500;
+    readonly TICKET_DESCRIPTION_MIN: 10;
+    readonly MESSAGE_CONTENT_MIN: 1;
+    readonly MESSAGE_CONTENT_MAX: 5000;
+    readonly FILE_NAME_MAX: 255;
+    readonly EXTERNAL_ID_MAX: 255;
+    readonly AVATAR_URL_MAX: 2048;
+};
+
+/**
+ * UTILIA OS SDK
+ *
+ * SDK JavaScript/TypeScript para integrar aplicaciones externas
+ * con el sistema de soporte de UTILIA OS.
+ *
+ * @example
+ * ```typescript
+ * import { UtiliaSDK } from '@utilia-os/sdk-js';
+ *
+ * const sdk = new UtiliaSDK({
+ *   baseURL: 'https://os.utilia.ai/api',
+ *   apiKey: 'tu-api-key',
+ * });
+ *
+ * // Identificar usuario
+ * const user = await sdk.users.identify({
+ *   externalId: 'user-123',
+ *   email: 'user@example.com',
+ * });
+ *
+ * // Crear ticket
+ * const ticket = await sdk.tickets.create({
+ *   user: { externalId: 'user-123' },
+ *   title: 'Problema con facturacion',
+ *   description: 'No puedo ver mis facturas...',
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Clase principal del SDK de UTILIA OS
+ *
+ * Proporciona acceso a todos los servicios disponibles:
+ * - `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 archivos adjuntos */
+    readonly files: FilesService;
+    /** Servicio de tickets de soporte */
+    readonly tickets: TicketsService;
+    /** Servicio de usuarios externos */
+    readonly users: UsersService;
+    /** Servicio de IA para transcripcion y sugerencias */
+    readonly ai: AiService;
+    /**
+     * Crea una nueva instancia del SDK
+     *
+     * @param config - Configuracion del SDK
+     *
+     * @example
+     * ```typescript
+     * const sdk = new UtiliaSDK({
+     *   baseURL: 'https://os.utilia.ai/api',
+     *   apiKey: 'tu-api-key',
+     *   timeout: 30000, // opcional
+     *   debug: true, // opcional, habilita logs
+     * });
+     *
+     * // Subir archivo y crear ticket con adjunto
+     * const file = await sdk.files.upload(inputFile);
+     * const ticket = await sdk.tickets.create({
+     *   user: { externalId: 'user-123' },
+     *   title: 'Problema con facturacion',
+     *   description: 'No puedo ver mis facturas...',
+     *   attachmentIds: [file.id],
+     * });
+     * ```
+     */
+    constructor(config: UtiliaSDKConfig);
+}
+
+export { type AddMessageInput, type AiJobStatus, type AiSuggestInput, type AiSuggestions, 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 TicketStatus, type UnreadCount, type UploadFileOptions, type UploadedFile, UtiliaSDK, type UtiliaSDKConfig, UtiliaSDKError };