@utilia-os/sdk-js 1.4.0 → 1.7.0

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // src/client.ts
-import axios, { AxiosError } from "axios";
+import axios2, { AxiosError } from "axios";
 
 // src/errors/sdk-error.ts
 var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
@@ -9,6 +9,7 @@ var ErrorCode = /* @__PURE__ */ ((ErrorCode2) => {
   ErrorCode2["RATE_LIMITED"] = "RATE_LIMITED";
   ErrorCode2["VALIDATION_ERROR"] = "VALIDATION_ERROR";
   ErrorCode2["NETWORK_ERROR"] = "NETWORK_ERROR";
+  ErrorCode2["AUTH_EXPIRED"] = "AUTH_EXPIRED";
   ErrorCode2["UNKNOWN"] = "UNKNOWN";
   return ErrorCode2;
 })(ErrorCode || {});
@@ -59,23 +60,469 @@ var UtiliaSDKError = class _UtiliaSDKError extends Error {
   }
 };
 
+// src/auth/oauth.service.ts
+import axios from "axios";
+
+// src/auth/pkce.ts
+function base64UrlEncode(buffer) {
+  const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateCodeVerifier(length = 64) {
+  const validLength = Math.max(43, Math.min(128, length));
+  const bytes = new Uint8Array(validLength);
+  crypto.getRandomValues(bytes);
+  return base64UrlEncode(bytes).slice(0, validLength);
+}
+async function generateCodeChallenge(verifier) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return base64UrlEncode(digest);
+}
+
+// src/auth/token-storage.ts
+var MemoryTokenStorage = class {
+  constructor() {
+    this.tokens = null;
+    this.pendingState = null;
+  }
+  async getTokens() {
+    return this.tokens;
+  }
+  async setTokens(tokens) {
+    this.tokens = tokens;
+  }
+  async clearTokens() {
+    this.tokens = null;
+  }
+  async getPendingState() {
+    return this.pendingState;
+  }
+  async setPendingState(state) {
+    this.pendingState = state;
+  }
+  async clearPendingState() {
+    this.pendingState = null;
+  }
+};
+var FileTokenStorage = class {
+  /**
+   * @param filePath - Ruta absoluta al archivo donde se guardarán los tokens
+   */
+  constructor(filePath) {
+    this.filePath = filePath;
+  }
+  async getTokens() {
+    try {
+      const fs = await import("fs/promises");
+      const content = await fs.readFile(this.filePath, "utf-8");
+      const data = JSON.parse(content);
+      if (data._pendingState) {
+        return null;
+      }
+      return data;
+    } catch {
+      return null;
+    }
+  }
+  async setTokens(tokens) {
+    const fs = await import("fs/promises");
+    await fs.writeFile(this.filePath, JSON.stringify(tokens, null, 2), { encoding: "utf-8", mode: 384 });
+  }
+  async clearTokens() {
+    try {
+      const fs = await import("fs/promises");
+      await fs.unlink(this.filePath);
+    } catch {
+    }
+  }
+  get pendingStatePath() {
+    return this.filePath.replace(/\.json$/, "") + ".pending.json";
+  }
+  async getPendingState() {
+    try {
+      const fs = await import("fs/promises");
+      const content = await fs.readFile(this.pendingStatePath, "utf-8");
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+  async setPendingState(state) {
+    const fs = await import("fs/promises");
+    await fs.writeFile(this.pendingStatePath, JSON.stringify(state, null, 2), { encoding: "utf-8", mode: 384 });
+  }
+  async clearPendingState() {
+    try {
+      const fs = await import("fs/promises");
+      await fs.unlink(this.pendingStatePath);
+    } catch {
+    }
+  }
+};
+
+// src/auth/oauth.service.ts
+var OAuthService = class {
+  constructor(baseURL, config) {
+    /** Estado PKCE en memoria como fallback cuando el storage no soporta pendingState */
+    this._pendingState = null;
+    this.baseURL = baseURL.replace(/\/$/, "");
+    this.config = config;
+    this.storage = config.tokenStorage ?? new MemoryTokenStorage();
+    this.http = axios.create({
+      baseURL: this.baseURL,
+      timeout: 3e4,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  /**
+   * 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
+   */
+  async getAuthorizationUrl(options) {
+    const result = await this.getLoginUrl(options);
+    const pending = {
+      codeVerifier: result.codeVerifier,
+      state: result.state
+    };
+    this._pendingState = pending;
+    if (this.storage.setPendingState) {
+      await this.storage.setPendingState(pending);
+    }
+    return result.url;
+  }
+  /**
+   * 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
+   */
+  async getLoginUrl(options) {
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const state = options?.state ?? Array.from(crypto.getRandomValues(new Uint8Array(24)), (b) => b.toString(16).padStart(2, "0")).join("");
+    const scopes = options?.scopes ?? this.config.scopes ?? ["openid", "profile", "email"];
+    const params = new URLSearchParams({
+      response_type: "code",
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      scope: scopes.join(" "),
+      state,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256"
+    });
+    return {
+      url: `${this.baseURL}/oauth/authorize?${params.toString()}`,
+      codeVerifier,
+      state
+    };
+  }
+  /**
+   * 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
+   */
+  async loginWithPopup(options) {
+    if (typeof window === "undefined") {
+      throw new Error("loginWithPopup solo est\xE1 disponible en entornos de navegador.");
+    }
+    const { url, codeVerifier, state } = await this.getLoginUrl({
+      state: options?.state,
+      scopes: options?.scopes
+    });
+    const width = options?.width ?? 500;
+    const height = options?.height ?? 700;
+    const timeout = options?.timeout ?? 3e5;
+    const left = Math.max(0, Math.round(window.screenX + (window.outerWidth - width) / 2));
+    const top = Math.max(0, Math.round(window.screenY + (window.outerHeight - height) / 2));
+    const features = `width=${width},height=${height},left=${left},top=${top},scrollbars=yes,resizable=yes,status=yes`;
+    const popup = window.open(url, "utilia-oauth-popup", features);
+    if (!popup || popup.closed) {
+      throw new Error(
+        "No se pudo abrir la ventana de autorizaci\xF3n. Verifica que los popups no est\xE9n bloqueados."
+      );
+    }
+    return new Promise((resolve, reject) => {
+      let timeoutId;
+      let pollId;
+      const cleanup = () => {
+        clearTimeout(timeoutId);
+        clearInterval(pollId);
+        window.removeEventListener("message", onMessage);
+      };
+      const onMessage = async (event) => {
+        if (event.origin !== window.location.origin) return;
+        const data = event.data;
+        if (!data || typeof data !== "object") return;
+        if (data.type === "oauth-mcp-success" && data.state === state) {
+          cleanup();
+          try {
+            if (popup && !popup.closed) popup.close();
+          } catch {
+          }
+          try {
+            const tokens = await this.handleCallback(data.code, codeVerifier);
+            resolve(tokens);
+          } catch (err) {
+            reject(err);
+          }
+        } else if (data.type === "oauth-mcp-error" && data.state === state) {
+          cleanup();
+          try {
+            if (popup && !popup.closed) popup.close();
+          } catch {
+          }
+          reject(new Error(data.error_description || data.error || "Autorizaci\xF3n denegada"));
+        }
+      };
+      window.addEventListener("message", onMessage);
+      pollId = setInterval(() => {
+        if (popup.closed) {
+          cleanup();
+          reject(new Error("La ventana de autorizaci\xF3n fue cerrada antes de completar el proceso."));
+        }
+      }, 500);
+      timeoutId = setTimeout(() => {
+        cleanup();
+        try {
+          if (popup && !popup.closed) popup.close();
+        } catch {
+        }
+        reject(new Error("El proceso de autorizaci\xF3n excedi\xF3 el tiempo l\xEDmite."));
+      }, timeout);
+    });
+  }
+  /**
+   * 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
+   */
+  async handleCallback(code, codeVerifier, callbackState) {
+    let verifier = codeVerifier;
+    if (!verifier) {
+      const pending = await this.getPendingState();
+      if (!pending) {
+        throw new Error(
+          "No se encontr\xF3 el estado PKCE pendiente. Usa getAuthorizationUrl() antes de handleCallback(), o proporciona el codeVerifier manualmente."
+        );
+      }
+      verifier = pending.codeVerifier;
+      if (callbackState && callbackState !== pending.state) {
+        await this.clearPendingState();
+        throw new Error(
+          `El valor de state no coincide. Posible ataque CSRF. Esperado: ${pending.state}, recibido: ${callbackState}`
+        );
+      }
+      await this.clearPendingState();
+    }
+    const body = {
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: this.config.redirectUri,
+      code_verifier: verifier,
+      client_id: this.config.clientId
+    };
+    if (this.config.clientSecret) {
+      body.client_secret = this.config.clientSecret;
+    }
+    const response = await this.http.post("/oauth/token", body);
+    const data = response.data;
+    const tokens = {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token,
+      expiresIn: data.expires_in,
+      expiresAt: Date.now() + data.expires_in * 1e3,
+      tokenType: data.token_type || "Bearer",
+      scope: data.scope,
+      idToken: data.id_token
+    };
+    await this.storage.setTokens(tokens);
+    return tokens;
+  }
+  /**
+   * Refresca el token de acceso usando el refresh_token
+   *
+   * @returns Nuevos tokens OAuth
+   * @throws Error si no hay refresh_token disponible
+   */
+  async refreshToken() {
+    const current = await this.storage.getTokens();
+    if (!current?.refreshToken) {
+      throw new Error("No hay refresh token disponible. El usuario debe volver a autenticarse.");
+    }
+    const body = {
+      grant_type: "refresh_token",
+      refresh_token: current.refreshToken,
+      client_id: this.config.clientId
+    };
+    if (this.config.clientSecret) {
+      body.client_secret = this.config.clientSecret;
+    }
+    const response = await this.http.post("/oauth/token", body);
+    const data = response.data;
+    const tokens = {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token ?? current.refreshToken,
+      expiresIn: data.expires_in,
+      expiresAt: Date.now() + data.expires_in * 1e3,
+      tokenType: data.token_type || "Bearer",
+      scope: data.scope,
+      idToken: data.id_token
+    };
+    await this.storage.setTokens(tokens);
+    return tokens;
+  }
+  /**
+   * Obtiene información del usuario autenticado
+   *
+   * @returns Datos del usuario desde /oauth/userinfo
+   */
+  async getUserInfo() {
+    const accessToken = await this.getAccessToken();
+    const response = await this.http.get("/oauth/userinfo", {
+      headers: { Authorization: `Bearer ${accessToken}` }
+    });
+    return response.data;
+  }
+  /**
+   * Revoca el token actual
+   *
+   * @param tokenType - Tipo de token a revocar ('access_token' | 'refresh_token').
+   *                     Por defecto revoca el access_token.
+   */
+  async revokeToken(tokenType) {
+    const current = await this.storage.getTokens();
+    if (!current) return;
+    const token = tokenType === "refresh_token" ? current.refreshToken : current.accessToken;
+    if (!token) return;
+    const body = {
+      token,
+      client_id: this.config.clientId
+    };
+    if (tokenType) {
+      body.token_type_hint = tokenType;
+    }
+    if (this.config.clientSecret) {
+      body.client_secret = this.config.clientSecret;
+    }
+    try {
+      await this.http.post("/oauth/revoke", body);
+    } catch {
+    }
+    await this.storage.clearTokens();
+  }
+  /**
+   * 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
+   */
+  async getAccessToken() {
+    const tokens = await this.storage.getTokens();
+    if (!tokens) {
+      throw new Error("No hay tokens OAuth. El usuario debe iniciar sesi\xF3n primero.");
+    }
+    if (tokens.expiresAt < Date.now() + 3e4) {
+      const refreshed = await this.refreshToken();
+      return refreshed.accessToken;
+    }
+    return tokens.accessToken;
+  }
+  /**
+   * 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)
+   */
+  async isAuthenticated() {
+    const tokens = await this.storage.getTokens();
+    if (!tokens) return false;
+    if (tokens.expiresAt > Date.now() + 3e4) return true;
+    return !!tokens.refreshToken;
+  }
+  /**
+   * Cierra la sesión OAuth: revoca los tokens y limpia el almacenamiento.
+   */
+  async logout() {
+    await this.revokeToken();
+  }
+  // -- Helpers internos para estado PKCE pendiente --
+  async getPendingState() {
+    if (this.storage.getPendingState) {
+      const stored = await this.storage.getPendingState();
+      if (stored) return stored;
+    }
+    return this._pendingState;
+  }
+  async clearPendingState() {
+    this._pendingState = null;
+    if (this.storage.clearPendingState) {
+      await this.storage.clearPendingState();
+    }
+  }
+};
+
 // src/client.ts
 var UtiliaClient = class {
   constructor(config) {
+    /** Promesa compartida para evitar refreshes concurrentes */
+    this._refreshPromise = null;
+    if (!config.apiKey && !config.oauth) {
+      throw new UtiliaSDKError(
+        "VALIDATION_ERROR" /* VALIDATION_ERROR */,
+        "Debes proporcionar apiKey o configuraci\xF3n oauth"
+      );
+    }
+    if (config.apiKey && config.oauth) {
+      throw new UtiliaSDKError(
+        "VALIDATION_ERROR" /* VALIDATION_ERROR */,
+        "No puedes proporcionar apiKey y oauth a la vez. Usa uno u otro."
+      );
+    }
     this.config = {
       timeout: 3e4,
       retryAttempts: 3,
       debug: false,
       ...config
     };
-    this.axios = axios.create({
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.config.apiKey) {
+      headers["X-Api-Key"] = this.config.apiKey;
+    }
+    this.axios = axios2.create({
       baseURL: this.config.baseURL,
       timeout: this.config.timeout,
-      headers: {
-        "Content-Type": "application/json",
-        "X-Api-Key": this.config.apiKey
-      }
+      headers
     });
+    if (this.config.oauth) {
+      this._oauthService = new OAuthService(this.config.baseURL, this.config.oauth);
+      if (this.config.oauth.tokenStorage) {
+      }
+      this.setupOAuthInterceptors();
+    }
     this.axios.interceptors.request.use((config2) => {
       const requestId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : this.generateSimpleId();
       config2.headers["x-request-id"] = requestId;
@@ -84,20 +531,71 @@ var UtiliaClient = class {
     });
     this.setupInterceptors();
   }
+  /**
+   * Acceso al servicio OAuth (solo disponible en modo OAuth)
+   */
+  get oauth() {
+    if (!this._oauthService) {
+      throw new UtiliaSDKError(
+        "VALIDATION_ERROR" /* VALIDATION_ERROR */,
+        "El servicio OAuth no est\xE1 disponible. Configura oauth en el constructor del SDK."
+      );
+    }
+    return this._oauthService;
+  }
+  /**
+   * Configura interceptores para autenticación OAuth
+   */
+  setupOAuthInterceptors() {
+    this.axios.interceptors.request.use(async (config) => {
+      if (this._oauthService) {
+        try {
+          const accessToken = await this._oauthService.getAccessToken();
+          config.headers["Authorization"] = `Bearer ${accessToken}`;
+        } catch {
+        }
+      }
+      return config;
+    });
+    this.axios.interceptors.response.use(
+      (response) => response,
+      async (error) => {
+        const originalRequest = error.config;
+        if (error.response?.status === 401 && this._oauthService && originalRequest && !originalRequest._retried) {
+          originalRequest._retried = true;
+          if (!this._refreshPromise) {
+            this._refreshPromise = this._oauthService.refreshToken().then(() => {
+            }).finally(() => {
+              this._refreshPromise = null;
+            });
+          }
+          try {
+            await this._refreshPromise;
+            const newToken = await this._oauthService.getAccessToken();
+            originalRequest.headers["Authorization"] = `Bearer ${newToken}`;
+            return this.axios(originalRequest);
+          } catch {
+            throw error;
+          }
+        }
+        throw error;
+      }
+    );
+  }
   /**
    * Configura los interceptores de request y response
    */
   setupInterceptors() {
     if (this.config.debug) {
       this.axios.interceptors.request.use((request) => {
-        console.log("[UtiliaSDK] Request:", request.method?.toUpperCase(), request.url);
+        console.log("[UtiliaSDK] Petici\xF3n:", request.method?.toUpperCase(), request.url);
         return request;
       });
     }
     if (this.config.debug) {
       this.axios.interceptors.response.use(
         (response) => {
-          console.log("[UtiliaSDK] Response:", response.status, response.config.url);
+          console.log("[UtiliaSDK] Respuesta:", response.status, response.config.url);
           return response;
         }
       );
@@ -114,15 +612,15 @@ var UtiliaClient = class {
     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);
+        return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Timeout: la solicitud excedi\xF3 el tiempo l\xEDmite", errorOptions);
       }
-      return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Error de conexion: no se pudo conectar con el servidor", errorOptions);
+      return new UtiliaSDKError("NETWORK_ERROR" /* NETWORK_ERROR */, "Error de conexi\xF3n: no se pudo conectar con el servidor", errorOptions);
     }
     const status = error.response.status;
     const message = data?.message || data?.error || error.message;
     switch (status) {
       case 401:
-        return new UtiliaSDKError("UNAUTHORIZED" /* UNAUTHORIZED */, message || "API Key invalida o faltante", errorOptions);
+        return new UtiliaSDKError("UNAUTHORIZED" /* UNAUTHORIZED */, message || "API Key inv\xE1lida 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.", errorOptions);
@@ -135,7 +633,7 @@ var UtiliaClient = class {
         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", errorOptions);
+        return new UtiliaSDKError("VALIDATION_ERROR" /* VALIDATION_ERROR */, message || "Error de validaci\xF3n en los datos enviados", errorOptions);
       case 429:
         return new UtiliaSDKError("RATE_LIMITED" /* RATE_LIMITED */, message || "Rate limit excedido. Intenta de nuevo mas tarde.", errorOptions);
       case 500:
@@ -148,7 +646,7 @@ var UtiliaClient = class {
     }
   }
   /**
-   * Determina si un error es recuperable y se debe reintentar
+   * Determina si un error es recuperable y se debe reintentar.
    */
   isRetryableError(error) {
     if (error instanceof AxiosError) {
@@ -162,7 +660,7 @@ var UtiliaClient = class {
     return false;
   }
   /**
-   * Ejecuta una funcion con reintentos y backoff exponencial
+   * Ejecuta una función con reintentos y backoff exponencial
    */
   async executeWithRetry(fn) {
     let lastError;
@@ -180,7 +678,7 @@ var UtiliaClient = class {
         if (attempt < this.config.retryAttempts - 1) {
           const delay = 500 * Math.pow(2, attempt);
           if (this.config.debug) {
-            console.log(`[UtiliaSDK] Retry attempt ${attempt + 1}/${this.config.retryAttempts - 1}, waiting ${delay}ms`);
+            console.log(`[UtiliaSDK] Reintento ${attempt + 1}/${this.config.retryAttempts - 1}, esperando ${delay}ms`);
           }
           await this.sleep(delay);
         }
@@ -192,7 +690,7 @@ var UtiliaClient = class {
     throw lastError;
   }
   /**
-   * Genera un ID simple como fallback cuando crypto.randomUUID no esta disponible
+   * Genera un ID simple como fallback cuando crypto.randomUUID no está disponible
    */
   generateSimpleId() {
     return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
@@ -204,19 +702,44 @@ var UtiliaClient = class {
     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.
+   * 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) {
     const base = this.config.baseURL.replace(/\/$/, "");
     const separator = path.includes("?") ? "&" : "?";
-    return `${base}${path}${separator}apiKey=${this.config.apiKey}`;
+    if (this.config.apiKey) {
+      return `${base}${path}${separator}apiKey=${this.config.apiKey}`;
+    }
+    return `${base}${path}`;
+  }
+  /**
+   * 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
+   */
+  async buildSseUrlAsync(path) {
+    const base = this.config.baseURL.replace(/\/$/, "");
+    const separator = path.includes("?") ? "&" : "?";
+    if (this.config.apiKey) {
+      return `${base}${path}${separator}apiKey=${this.config.apiKey}`;
+    }
+    if (this._oauthService) {
+      try {
+        const accessToken = await this._oauthService.getAccessToken();
+        return `${base}${path}${separator}access_token=${accessToken}`;
+      } catch {
+      }
+    }
+    return `${base}${path}`;
   }
   /**
-   * Realiza una peticion GET
+   * Realiza una petición GET
    */
   async get(url, config) {
     return this.executeWithRetry(async () => {
@@ -596,6 +1119,54 @@ var TicketsService = class {
       { params: { userId } }
     );
   }
+  /**
+   * Suscribirse a actualizaciones de tickets en tiempo real via SSE.
+   * Recibe eventos cuando un agente responde, cambia el estado, resuelve o cierra un ticket.
+   *
+   * Requiere un entorno con EventSource nativo (navegador) o un polyfill como 'eventsource'.
+   *
+   * @param userId - ID externo del usuario (opcional, filtra eventos por usuario)
+   * @param options - Callbacks para eventos y errores
+   * @returns Objeto con metodo close() para cerrar la conexion
+   *
+   * @example
+   * ```typescript
+   * const stream = sdk.tickets.streamUpdates('user-123', {
+   *   onTicketUpdated: (event) => {
+   *     console.log(`Ticket ${event.ticketKey} actualizado: ${event.type}`);
+   *     // Refrescar la UI del ticket
+   *   },
+   * });
+   *
+   * // Para cerrar la conexion:
+   * stream.close();
+   * ```
+   */
+  streamUpdates(userId, 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 queryParams = userId ? `?userId=${encodeURIComponent(userId)}` : "";
+    const sseUrl = this.client.buildSseUrl(`${this.basePath}/events${queryParams}`);
+    const eventSource = new EventSource(sseUrl);
+    eventSource.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        if (data.event === "ticket-updated" && options?.onTicketUpdated) {
+          options.onTicketUpdated(data);
+        }
+      } catch {
+      }
+    };
+    eventSource.onerror = () => {
+      options?.onError?.(new Error("Error en la conexion SSE"));
+    };
+    return {
+      close: () => eventSource.close()
+    };
+  }
   /**
    * Cerrar un ticket
    * Solo el usuario que creo el ticket puede cerrarlo
@@ -1101,39 +1672,57 @@ var UtiliaSDK = class {
   /**
    * 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) {
-    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);
-    this.ai = new AiService(client);
+    this._client = new UtiliaClient(config);
+    this.errors = new ErrorsService(this._client);
+    this.files = new FilesService(this._client);
+    this.tickets = new TicketsService(this._client);
+    this.users = new UsersService(this._client);
+    this.ai = new AiService(this._client);
+  }
+  /**
+   * Servicio OAuth (solo disponible si se configuro oauth en el constructor)
+   */
+  get oauth() {
+    return this._client.oauth;
   }
 };
 export {
   ErrorCode,
+  FileTokenStorage,
+  MemoryTokenStorage,
+  OAuthService,
   SDK_LIMITS,
   UtiliaSDK,
-  UtiliaSDKError
+  UtiliaSDKError,
+  base64UrlEncode,
+  generateCodeChallenge,
+  generateCodeVerifier
 };