@utilia-os/sdk-js 1.5.0 → 1.7.0

package/dist/index.d.mts

@@ -1,14 +1,137 @@
 /**
- * Tipos de configuracion del SDK
+ * Tipos para autenticación OAuth 2.1 con PKCE
  */
+/**
+ * Configuración de OAuth para el SDK
+ */
+interface OAuthConfig {
+    /** Identificador de la aplicación OAuth */
+    clientId: string;
+    /** Secreto de la aplicación (opcional, para apps confidenciales) */
+    clientSecret?: string;
+    /** URI de redirección registrada */
+    redirectUri: string;
+    /** Scopes solicitados (default: ['openid', 'profile', 'email']) */
+    scopes?: string[];
+    /** Almacenamiento personalizado de tokens */
+    tokenStorage?: TokenStorage;
+}
+/**
+ * Tokens OAuth devueltos por el servidor de autorización
+ */
+interface OAuthTokens {
+    /** Token de acceso */
+    accessToken: string;
+    /** Token de refresco (si fue concedido) */
+    refreshToken?: string;
+    /** Duración en segundos del access token */
+    expiresIn: number;
+    /** Timestamp absoluto de expiración (Date.now() + expiresIn * 1000) */
+    expiresAt: number;
+    /** Tipo de token (normalmente 'Bearer') */
+    tokenType: string;
+    /** Scopes concedidos */
+    scope?: string;
+    /** Token de identidad OpenID Connect */
+    idToken?: string;
+}
+/**
+ * Información del usuario autenticado (endpoint /oauth/userinfo)
+ */
+interface OAuthUserInfo {
+    /** Identificador único del usuario */
+    sub: string;
+    /** Nombre completo */
+    name?: string;
+    /** Correo electrónico */
+    email?: string;
+    /** Si el correo ha sido verificado */
+    email_verified?: boolean;
+    /** URL de la foto de perfil */
+    picture?: string;
+    /** Nombre de pila */
+    given_name?: string;
+    /** Apellido(s) */
+    family_name?: string;
+    /** Campos adicionales */
+    [key: string]: unknown;
+}
+/**
+ * Interfaz para almacenamiento personalizado de tokens
+ */
+interface TokenStorage {
+    /** Obtiene los tokens almacenados */
+    getTokens(): Promise<OAuthTokens | null>;
+    /** Almacena los tokens */
+    setTokens(tokens: OAuthTokens): Promise<void>;
+    /** Elimina los tokens almacenados */
+    clearTokens(): Promise<void>;
+    /** Obtiene el estado PKCE pendiente (opcional, para flujo automático) */
+    getPendingState?(): Promise<PendingOAuthState | null>;
+    /** Almacena el estado PKCE pendiente (opcional, para flujo automático) */
+    setPendingState?(state: PendingOAuthState): Promise<void>;
+    /** Elimina el estado PKCE pendiente (opcional, para flujo automático) */
+    clearPendingState?(): Promise<void>;
+}
+/**
+ * Par de desafío PKCE (code_verifier + code_challenge)
+ */
+interface PKCEChallenge {
+    /** Cadena aleatoria usada como verificador */
+    codeVerifier: string;
+    /** Hash SHA-256 base64url del verificador */
+    codeChallenge: string;
+}
+/**
+ * Estado PKCE pendiente almacenado entre getAuthorizationUrl() y handleCallback()
+ */
+interface PendingOAuthState {
+    /** Verificador PKCE generado */
+    codeVerifier: string;
+    /** Valor de state para protección CSRF */
+    state: string;
+}
+/**
+ * Resultado de generar la URL de inicio de sesión
+ */
+interface LoginUrlResult {
+    /** URL completa de autorización */
+    url: string;
+    /** Verificador PKCE (debe guardarse para el callback) */
+    codeVerifier: string;
+    /** Valor de state para protección CSRF */
+    state: string;
+}
+/**
+ * Opciones para inicio de sesión OAuth mediante ventana emergente
+ */
+interface PopupLoginOptions {
+    /** Parámetro state personalizado para protección CSRF */
+    state?: string;
+    /** Scopes a solicitar */
+    scopes?: string[];
+    /** Ancho de la ventana emergente en píxeles (por defecto: 500) */
+    width?: number;
+    /** Alto de la ventana emergente en píxeles (por defecto: 700) */
+    height?: number;
+    /** Tiempo límite en milisegundos antes de rechazar (por defecto: 300000 = 5 min) */
+    timeout?: number;
+}
+
+/**
+ * Tipos de configuración del SDK
+ */
+
 interface UtiliaSDKConfig {
     /** URL base de la API (ej: https://os.utilia.ai/api) */
     baseURL: string;
-    /** API Key para autenticacion */
-    apiKey: string;
+    /** API Key para autenticación (requerida si no se usa OAuth) */
+    apiKey?: string;
+    /** Configuración OAuth 2.1 con PKCE (alternativa a apiKey) */
+    oauth?: OAuthConfig;
     /** Timeout en milisegundos (default: 30000) */
     timeout?: number;
-    /** Numero de reintentos en caso de error (default: 3) */
+    /** Número de reintentos en caso de error (default: 3) */
     retryAttempts?: number;
     /** Habilitar logs de debug (default: false) */
     debug?: boolean;
@@ -18,6 +141,109 @@ interface RequestConfig {
     params?: Record<string, unknown>;
 }
 
+/**
+ * Servicio OAuth 2.1 con PKCE para el SDK de UTILIA OS
+ */
+
+/**
+ * Servicio que gestiona el flujo OAuth 2.1 con PKCE
+ */
+declare class OAuthService {
+    private readonly baseURL;
+    private readonly config;
+    private readonly storage;
+    private readonly http;
+    /** Estado PKCE en memoria como fallback cuando el storage no soporta pendingState */
+    private _pendingState;
+    constructor(baseURL: string, config: OAuthConfig);
+    /**
+     * Genera la URL de autorización OAuth con PKCE y almacena el estado
+     * pendiente automáticamente. Usar con handleCallback(code) sin codeVerifier.
+     *
+     * Este es el método recomendado para la mayoría de los casos.
+     *
+     * @param options - Opciones adicionales (state personalizado, scopes)
+     * @returns URL de autorización lista para redirigir al usuario
+     */
+    getAuthorizationUrl(options?: {
+        state?: string;
+        scopes?: string[];
+    }): Promise<string>;
+    /**
+     * Genera la URL de inicio de sesión OAuth con PKCE.
+     *
+     * Método de control manual: devuelve codeVerifier y state que el desarrollador
+     * debe gestionar. Para un flujo automático, usar getAuthorizationUrl() en su lugar.
+     *
+     * @param options - Opciones adicionales (state personalizado, scopes)
+     * @returns URL de autorización, code_verifier y state
+     */
+    getLoginUrl(options?: {
+        state?: string;
+        scopes?: string[];
+    }): Promise<LoginUrlResult>;
+    /**
+     * Abre una ventana emergente para inicio de sesión OAuth y devuelve tokens al completarse.
+     *
+     * @param options - Opciones de configuración de la ventana emergente
+     * @returns Tokens OAuth
+     * @throws Error si la ventana es bloqueada, cerrada o excede el tiempo límite
+     */
+    loginWithPopup(options?: PopupLoginOptions): Promise<OAuthTokens>;
+    /**
+     * Intercambia el código de autorización por tokens.
+     *
+     * Si se llama sin codeVerifier, recupera automáticamente el estado PKCE
+     * almacenado por getAuthorizationUrl() y valida el state CSRF.
+     *
+     * @param code - Código de autorización recibido en el callback
+     * @param codeVerifier - Verificador PKCE (opcional si se usó getAuthorizationUrl)
+     * @param callbackState - Valor de state recibido en el callback (para validación CSRF automática)
+     * @returns Tokens OAuth
+     */
+    handleCallback(code: string, codeVerifier?: string, callbackState?: string): Promise<OAuthTokens>;
+    /**
+     * Refresca el token de acceso usando el refresh_token
+     *
+     * @returns Nuevos tokens OAuth
+     * @throws Error si no hay refresh_token disponible
+     */
+    refreshToken(): Promise<OAuthTokens>;
+    /**
+     * Obtiene información del usuario autenticado
+     *
+     * @returns Datos del usuario desde /oauth/userinfo
+     */
+    getUserInfo(): Promise<OAuthUserInfo>;
+    /**
+     * Revoca el token actual
+     *
+     * @param tokenType - Tipo de token a revocar ('access_token' | 'refresh_token').
+     *                     Por defecto revoca el access_token.
+     */
+    revokeToken(tokenType?: 'access_token' | 'refresh_token'): Promise<void>;
+    /**
+     * Obtiene un access token válido, refrescándolo automáticamente si ha expirado
+     *
+     * @returns Access token válido
+     * @throws Error si no hay tokens disponibles
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Verifica si hay una sesión OAuth activa con tokens válidos.
+     *
+     * @returns true si hay tokens almacenados y el access token no ha expirado
+     *          (o si hay un refresh token disponible para renovarlo)
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Cierra la sesión OAuth: revoca los tokens y limpia el almacenamiento.
+     */
+    logout(): Promise<void>;
+    private getPendingState;
+    private clearPendingState;
+}
+
 /**
  * Cliente HTTP base para el SDK
  * Maneja la comunicacion con la API de UTILIA OS
@@ -26,7 +252,18 @@ interface RequestConfig {
 declare class UtiliaClient {
     private readonly axios;
     private readonly config;
+    private readonly _oauthService?;
+    /** Promesa compartida para evitar refreshes concurrentes */
+    private _refreshPromise;
     constructor(config: UtiliaSDKConfig);
+    /**
+     * Acceso al servicio OAuth (solo disponible en modo OAuth)
+     */
+    get oauth(): OAuthService;
+    /**
+     * Configura interceptores para autenticación OAuth
+     */
+    private setupOAuthInterceptors;
     /**
      * Configura los interceptores de request y response
      */
@@ -36,15 +273,15 @@ declare class UtiliaClient {
      */
     private toSDKError;
     /**
-     * Determina si un error es recuperable y se debe reintentar
+     * Determina si un error es recuperable y se debe reintentar.
      */
     private isRetryableError;
     /**
-     * Ejecuta una funcion con reintentos y backoff exponencial
+     * Ejecuta una función con reintentos y backoff exponencial
      */
     private executeWithRetry;
     /**
-     * Genera un ID simple como fallback cuando crypto.randomUUID no esta disponible
+     * Genera un ID simple como fallback cuando crypto.randomUUID no está disponible
      */
     private generateSimpleId;
     /**
@@ -52,15 +289,23 @@ declare class UtiliaClient {
      */
     private sleep;
     /**
-     * Construye una URL completa para conexiones SSE con la API key como query param.
-     * Util para EventSource que no soporta headers personalizados.
+     * Construye una URL completa para conexiones SSE con credenciales como query param.
+     * Necesario porque EventSource 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
+     * @returns URL completa con credenciales como parametro de consulta
      */
     buildSseUrl(path: string): string;
     /**
-     * Realiza una peticion GET
+     * Construye una URL completa para conexiones SSE, incluyendo token OAuth si está disponible.
+     * Versión asíncrona que obtiene el access token actual.
+     *
+     * @param path - Ruta relativa de la API
+     * @returns URL completa con credenciales como parametro de consulta
+     */
+    buildSseUrlAsync(path: string): Promise<string>;
+    /**
+     * Realiza una petición GET
      */
     get<T>(url: string, config?: RequestConfig): Promise<T>;
     /**
@@ -1222,6 +1467,8 @@ declare enum ErrorCode {
     VALIDATION_ERROR = "VALIDATION_ERROR",
     /** Error de conexion de red */
     NETWORK_ERROR = "NETWORK_ERROR",
+    /** Sesión OAuth expirada (access token y refresh token inválidos) */
+    AUTH_EXPIRED = "AUTH_EXPIRED",
     /** Error desconocido */
     UNKNOWN = "UNKNOWN"
 }
@@ -1271,6 +1518,67 @@ declare class UtiliaSDKError extends Error {
     isRetryable(): boolean;
 }
 
+/**
+ * Implementaciones de almacenamiento de tokens OAuth
+ */
+
+/**
+ * Almacenamiento de tokens en memoria.
+ * Los tokens se pierden al cerrar el proceso.
+ */
+declare class MemoryTokenStorage implements TokenStorage {
+    private tokens;
+    private pendingState;
+    getTokens(): Promise<OAuthTokens | null>;
+    setTokens(tokens: OAuthTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+    getPendingState(): Promise<PendingOAuthState | null>;
+    setPendingState(state: PendingOAuthState): Promise<void>;
+    clearPendingState(): Promise<void>;
+}
+/**
+ * Almacenamiento de tokens en archivo JSON (solo Node.js).
+ * Persiste los tokens entre ejecuciones.
+ */
+declare class FileTokenStorage implements TokenStorage {
+    private readonly filePath;
+    /**
+     * @param filePath - Ruta absoluta al archivo donde se guardarán los tokens
+     */
+    constructor(filePath: string);
+    getTokens(): Promise<OAuthTokens | null>;
+    setTokens(tokens: OAuthTokens): Promise<void>;
+    clearTokens(): Promise<void>;
+    private get pendingStatePath();
+    getPendingState(): Promise<PendingOAuthState | null>;
+    setPendingState(state: PendingOAuthState): Promise<void>;
+    clearPendingState(): Promise<void>;
+}
+
+/**
+ * Utilidades PKCE (Proof Key for Code Exchange) para OAuth 2.1
+ *
+ * Usa crypto.getRandomValues y crypto.subtle, disponibles tanto en
+ * navegador como en Node.js >= 18.
+ */
+/**
+ * Codifica un ArrayBuffer/Uint8Array en base64url (sin padding)
+ */
+declare function base64UrlEncode(buffer: ArrayBuffer | Uint8Array): string;
+/**
+ * Genera un code_verifier aleatorio compatible con RFC 7636
+ *
+ * @param length - Longitud del verificador (entre 43 y 128, default: 64)
+ */
+declare function generateCodeVerifier(length?: number): string;
+/**
+ * Genera el code_challenge a partir de un code_verifier usando SHA-256
+ *
+ * @param verifier - El code_verifier generado previamente
+ * @returns code_challenge en base64url
+ */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+
 /**
  * Constantes y limites del SDK
  */
@@ -1325,9 +1633,10 @@ declare const SDK_LIMITS: {
  * - `files`: Operaciones con archivos adjuntos
  * - `tickets`: Operaciones con tickets de soporte
  * - `users`: Operaciones con usuarios externos
- * - `ai`: Funcionalidades de IA (transcripcion, sugerencias)
+ * - `ai`: Funcionalidades de IA (transcripción, sugerencias)
  */
 declare class UtiliaSDK {
+    private readonly _client;
     /** Servicio de errores del sistema */
     readonly errors: ErrorsService;
     /** Servicio de archivos adjuntos */
@@ -1336,33 +1645,43 @@ declare class UtiliaSDK {
     readonly tickets: TicketsService;
     /** Servicio de usuarios externos */
     readonly users: UsersService;
-    /** Servicio de IA para transcripcion y sugerencias */
+    /** Servicio de IA para transcripción y sugerencias */
     readonly ai: AiService;
     /**
      * Crea una nueva instancia del SDK
      *
-     * @param config - Configuracion del SDK
+     * @param config - Configuración del SDK
      *
-     * @example
+     * @example Autenticación con API Key
      * ```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],
+     * @example Autenticación con OAuth 2.1 + PKCE
+     * ```typescript
+     * const sdk = new UtiliaSDK({
+     *   baseURL: 'https://os.utilia.ai/api',
+     *   oauth: {
+     *     clientId: 'tu-client-id',
+     *     redirectUri: 'https://tu-app.com/callback',
+     *   },
      * });
+     *
+     * // Obtener URL de autorización (gestiona PKCE automáticamente)
+     * const authUrl = await sdk.oauth.getAuthorizationUrl();
+     *
+     * // Tras el callback (recupera PKCE automáticamente)
+     * const tokens = await sdk.oauth.handleCallback(code);
      * ```
      */
     constructor(config: UtiliaSDKConfig);
+    /**
+     * Servicio OAuth (solo disponible si se configuro oauth en el constructor)
+     */
+    get oauth(): OAuthService;
 }
 
-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 };
+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, FileTokenStorage, type GetSuggestionsOptions, type IdentifyUserInput, type LoginUrlResult, MemoryTokenStorage, type MessageAuthor, type OAuthConfig, OAuthService, type OAuthTokens, type OAuthUserInfo, type PKCEChallenge, type PaginatedResponse, type PaginationMeta, type PendingOAuthState, type PopupLoginOptions, 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 TokenStorage, type TrackAiActionInput, type TranscriptionJobStatus, type UnreadCount, type UploadFileOptions, type UploadedFile, UtiliaSDK, type UtiliaSDKConfig, UtiliaSDKError, base64UrlEncode, generateCodeChallenge, generateCodeVerifier };