@bereasoftware/nexa 1.3.0 → 1.4.1

package/README.en.md

@@ -954,9 +954,11 @@ manager.register(rateLimitPlugin);
 
 ---
 
-## Dev Overlay
-
-Built-in visual development tool for debugging and monitoring HTTP requests in real-time.
+## Dev Overlay
+
+Built-in visual development tool for debugging and monitoring HTTP requests in real-time.
+
+> API status: publicly available and intended for browser development flows. It is not designed for SSR or Node runtimes without a DOM.
 
 ```typescript
 import { createHttpClient, createDevOverlay } from "@bereasoftware/nexa";
@@ -1007,8 +1009,10 @@ createDevOverlay(config?: DevOverlayConfig): { tracker: RequestTracker; ui: DevO
 **Behavior notes:**
 
 - `createDevOverlay()` is a singleton. Multiple calls reuse the same instance.
+- The overlay only mounts UI when a DOM is available. In SSR or Node you can import the module safely, but no panel is rendered.
 - `theme` is typed as `'dark' | 'light'`, but the current UI is primarily designed for dark mode.
 - The retry button uses direct `fetch()` for quick revalidation; it does not automatically replay interceptors or advanced `HttpClient` configuration.
+- `destroyDevOverlay()` clears the singleton instance, removes the panel, and unregisters the global listeners used by the overlay.
 
 **Note:** Advanced request options such as `transformRequest`, `credentials`, `withCredentials`, `debug`, `logger`, `transport`, `nodeOptions`, and `autoFormData` are already typed, but not all of them are fully wired into the main `HttpClient` pipeline in this release.
 
@@ -1034,6 +1038,13 @@ getDevOverlay() // Get current { tracker, ui } or null if not created yet
 destroyDevOverlay() // Destroy the current singleton instance
 ```
 
+**When to use each export:**
+
+- `createDevOverlay()` creates or reuses the overlay and returns the `tracker` you pass into `createHttpClient({ devTracker })`.
+- `getDevOverlay()` lets you inspect the current instance without creating a new one.
+- `destroyDevOverlay()` is useful for full teardown during hot reloads, tests, or manual cleanup.
+- `RequestTracker` can be used on its own if you want request history and metrics without mounting the UI.
+
 **Exposed data shapes:**
 
 ```typescript

package/README.md

@@ -1291,9 +1291,11 @@ manager.register(rateLimitPlugin);
 
 ---
 
-## Dev Overlay
-
-Herramienta visual de desarrollo integrada para depurar y monitorear requests HTTP en tiempo real.
+## Dev Overlay
+
+Herramienta visual de desarrollo integrada para depurar y monitorear requests HTTP en tiempo real.
+
+> Estado de API: disponible públicamente y pensada para flujos de desarrollo en navegador. No está orientada a entornos SSR o Node sin DOM.
 
 ```typescript
 import { createHttpClient, createDevOverlay } from "@bereasoftware/nexa";
@@ -1344,8 +1346,10 @@ createDevOverlay(config?: DevOverlayConfig): { tracker: RequestTracker; ui: DevO
 **Notas de comportamiento:**
 
 - `createDevOverlay()` es singleton. Si lo llamas varias veces, reutiliza la misma instancia.
+- El overlay solo monta UI cuando hay DOM disponible. En SSR o Node puedes importar el módulo sin romper el proceso, pero no se renderiza panel.
 - `theme` está tipado como `'dark' | 'light'`, pero la UI actual está diseñada principalmente para tema oscuro.
 - El botón de retry del panel usa `fetch()` directo para revalidación rápida; no reaplica automáticamente interceptores ni configuración avanzada del `HttpClient`.
+- `destroyDevOverlay()` limpia la instancia singleton, desmonta el panel y remueve listeners globales registrados por el overlay.
 
 **Métodos del UI:**
 
@@ -1369,6 +1373,13 @@ getDevOverlay() // Obtener { tracker, ui } actuales o null si no existen
 destroyDevOverlay() // Destruir la instancia singleton actual
 ```
 
+**Cuándo usar cada export:**
+
+- `createDevOverlay()` crea o reutiliza el overlay y devuelve el `tracker` que debes pasar a `createHttpClient({ devTracker })`.
+- `getDevOverlay()` te permite consultar la instancia actual sin crear una nueva.
+- `destroyDevOverlay()` sirve para cerrar completamente la herramienta en hot reloads, tests o limpieza manual.
+- `RequestTracker` puede usarse por separado si quieres recolectar historial y métricas sin montar la UI.
+
 **Estructuras expuestas:**
 
 ```typescript

package/dist/nexa.cjs.js

@@ -334,7 +334,7 @@ Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=e=>({ok
     align-items: center;
     gap: 8px;
   }
-`,ye=class{panel=null;tracker;visible=!1;selectedRequest=null;config;searchQuery=``;constructor(e){this.tracker=e,this.config=e.getConfig(),this.setupKeyboardShortcut(),this.createPanel()}show(){this.panel&&(this.panel.style.display=`flex`,this.panel.style.opacity=`0`,this.panel.style.transform=`scale(0.96) translateY(8px)`,requestAnimationFrame(()=>{this.panel.style.transition=`all 0.25s cubic-bezier(0.16, 1, 0.3, 1)`,this.panel.style.opacity=`1`,this.panel.style.transform=`scale(1) translateY(0)`}),this.visible=!0)}hide(){this.panel&&(this.panel.style.transition=`all 0.15s ease-out`,this.panel.style.opacity=`0`,this.panel.style.transform=`scale(0.96) translateY(8px)`,setTimeout(()=>{this.panel&&(this.panel.style.display=`none`)},150),this.visible=!1)}toggle(){this.visible?this.hide():this.show()}destroy(){this.panel?.remove(),this.panel=null}setupKeyboardShortcut(){let e=this.config.keyboardShortcut.split(`+`),t=new Set(e.map(e=>e.toLowerCase()));document.addEventListener(`keydown`,e=>{let n=new Set;e.ctrlKey&&n.add(`ctrl`),e.metaKey&&(n.add(`meta`),n.add(`cmd`),n.add(`ctrl`)),e.shiftKey&&n.add(`shift`),e.altKey&&n.add(`alt`),(e.key&&e.key.length===1||e.key.length>1)&&n.add(e.key.toLowerCase());let r=!0;for(let e of t)if(!n.has(e)){r=!1;break}r&&n.size===t.size&&(e.preventDefault(),this.toggle())})}createPanel(){this.panel=document.createElement(`div`),this.panel.id=`nexa-dev-overlay`;let e=this.config.position,t=e.includes(`bottom`),n=e.includes(`right`);this.panel.style.cssText=`
+`,ye=class{panel=null;tracker;visible=!1;selectedRequest=null;config;searchQuery=``;removeTrackerListener=null;keyboardShortcutHandler=null;globalKeyboardHandler=null;constructor(e){this.tracker=e,this.config=e.getConfig(),this.canUseDOM()&&(this.setupKeyboardShortcut(),this.createPanel())}show(){this.panel&&(this.panel.style.display=`flex`,this.panel.style.opacity=`0`,this.panel.style.transform=`scale(0.96) translateY(8px)`,(typeof requestAnimationFrame==`function`?requestAnimationFrame:e=>setTimeout(e,0))(()=>{this.panel.style.transition=`all 0.25s cubic-bezier(0.16, 1, 0.3, 1)`,this.panel.style.opacity=`1`,this.panel.style.transform=`scale(1) translateY(0)`}),this.visible=!0)}hide(){this.panel&&(this.panel.style.transition=`all 0.15s ease-out`,this.panel.style.opacity=`0`,this.panel.style.transform=`scale(0.96) translateY(8px)`,setTimeout(()=>{this.panel&&(this.panel.style.display=`none`)},150),this.visible=!1)}toggle(){this.visible?this.hide():this.show()}destroy(){this.keyboardShortcutHandler&&=(document.removeEventListener(`keydown`,this.keyboardShortcutHandler),null),this.globalKeyboardHandler&&=(document.removeEventListener(`keydown`,this.globalKeyboardHandler),null),this.removeTrackerListener?.(),this.removeTrackerListener=null,this.panel?.remove(),this.panel=null,this.visible=!1,this.selectedRequest=null}setupKeyboardShortcut(){let e=this.config.keyboardShortcut.split(`+`),t=new Set(e.map(e=>e.toLowerCase()));this.keyboardShortcutHandler=e=>{let n=new Set;e.ctrlKey&&n.add(`ctrl`),e.metaKey&&(n.add(`meta`),n.add(`cmd`),n.add(`ctrl`)),e.shiftKey&&n.add(`shift`),e.altKey&&n.add(`alt`),(e.key&&e.key.length===1||e.key.length>1)&&n.add(e.key.toLowerCase());let r=!0;for(let e of t)if(!n.has(e)){r=!1;break}r&&n.size===t.size&&(e.preventDefault(),this.toggle())},document.addEventListener(`keydown`,this.keyboardShortcutHandler)}createPanel(){if(!this.canUseDOM())return;this.panel=document.createElement(`div`),this.panel.id=`nexa-dev-overlay`;let e=this.config.position,t=e.includes(`bottom`),n=e.includes(`right`);this.panel.style.cssText=`
       position: fixed;
       ${t?`bottom: 24px;`:`top: 24px;`}
       ${n?`right: 24px;`:`left: 24px;`}
@@ -349,8 +349,7 @@ Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=e=>({ok
       <div class="nexa-header">
 <div class="nexa-header-left">
           <div class="nexa-logo">
-            <img src="/src/assets/faviconNew.png" width="18" height="18" style="border-radius:4px;object-fit:contain;display:block;" alt="Nexa" onerror="this.style.display='none';this.nextElementSibling.style.display='flex';" />
-            <span style="display:none;align-items:center;justify-content:center;font-size:14px;font-weight:700;color:#fff;background:linear-gradient(135deg,#3b82f6,#238636);width:18px;height:18px;border-radius:4px;">N</span>
+            <span style="display:flex;align-items:center;justify-content:center;font-size:14px;font-weight:700;color:#fff;background:linear-gradient(135deg,#3b82f6,#238636);width:18px;height:18px;border-radius:4px;">N</span>
           </div>
           <span class="nexa-title">Nexa DevTools</span>
         </div>
@@ -390,7 +389,7 @@ Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=e=>({ok
         </div>
         <div class="nexa-detail-body"></div>
       </div>
-    `,document.body.appendChild(this.panel),this.bindEvents(),this.tracker.onChange(()=>this.render()),this.hide(),document.addEventListener(`keydown`,e=>{if(e.key===`Escape`&&this.visible){this.hide();return}if(this.visible&&(e.ctrlKey||e.metaKey)&&e.key.toLowerCase()===`f`){e.preventDefault();let t=this.panel?.querySelector(`.nexa-search-input`);t?.focus(),t?.select()}})}bindEvents(){this.panel&&(this.panel.querySelector(`.nexa-btn-close`)?.addEventListener(`click`,()=>this.hide()),this.panel.querySelector(`.nexa-btn-clear`)?.addEventListener(`click`,()=>{this.tracker.clear(),this.render()}),this.panel.querySelector(`.nexa-btn-back`)?.addEventListener(`click`,()=>this.showMainView()),this.panel.querySelector(`.nexa-btn-retry`)?.addEventListener(`click`,()=>this.retrySelected()),this.panel.querySelector(`.nexa-search-input`)?.addEventListener(`input`,e=>{this.searchQuery=e.target.value.toLowerCase(),this.renderRequestList()}),this.panel.querySelectorAll(`.nexa-tab`).forEach(e=>{e.addEventListener(`click`,()=>{this.panel.querySelectorAll(`.nexa-tab`).forEach(e=>e.classList.remove(`nexa-tab-active`)),this.panel.querySelectorAll(`.nexa-panel`).forEach(e=>e.classList.remove(`nexa-panel-active`)),e.classList.add(`nexa-tab-active`),this.panel.querySelector(`[data-panel="${e.dataset.tab}"]`)?.classList.add(`nexa-panel-active`),e.dataset.tab===`metrics`&&this.renderMetrics()})}))}render(){!this.panel||!this.visible||(this.renderMetricsBar(),this.renderRequestList())}renderMetricsBar(){let e=this.tracker.getMetrics(),t=this.panel;t&&(t.querySelector(`[data-metric="total"]`).textContent=String(e.totalRequests),t.querySelector(`[data-metric="avg"]`).textContent=`${e.avgDuration.toFixed(0)}ms`,t.querySelector(`[data-metric="rate"]`).textContent=`${e.requestsPerSecond.toFixed(1)}`,t.querySelector(`[data-metric="success"]`).textContent=String(e.successfulRequests),t.querySelector(`[data-metric="fail"]`).textContent=String(e.failedRequests),t.querySelector(`[data-count="requests"]`).textContent=String(e.totalRequests))}renderRequestList(){let e=this.panel?.querySelector(`.nexa-request-list`);if(!e)return;let t=this.tracker.getHistory();if(this.searchQuery&&(t=t.filter(e=>e.url.toLowerCase().includes(this.searchQuery)||e.method.toLowerCase().includes(this.searchQuery)||String(e.status).includes(this.searchQuery))),t.length===0){e.innerHTML=`
+    `,document.body.appendChild(this.panel),this.bindEvents(),this.removeTrackerListener=this.tracker.onChange(()=>this.render()),this.hide(),this.globalKeyboardHandler=e=>{if(e.key===`Escape`&&this.visible){this.hide();return}if(this.visible&&(e.ctrlKey||e.metaKey)&&e.key.toLowerCase()===`f`){e.preventDefault();let t=this.panel?.querySelector(`.nexa-search-input`);t?.focus(),t?.select()}},document.addEventListener(`keydown`,this.globalKeyboardHandler)}bindEvents(){this.panel&&(this.panel.querySelector(`.nexa-btn-close`)?.addEventListener(`click`,()=>this.hide()),this.panel.querySelector(`.nexa-btn-clear`)?.addEventListener(`click`,()=>{this.tracker.clear(),this.render()}),this.panel.querySelector(`.nexa-btn-back`)?.addEventListener(`click`,()=>this.showMainView()),this.panel.querySelector(`.nexa-btn-retry`)?.addEventListener(`click`,()=>this.retrySelected()),this.panel.querySelector(`.nexa-search-input`)?.addEventListener(`input`,e=>{this.searchQuery=e.target.value.toLowerCase(),this.renderRequestList()}),this.panel.querySelectorAll(`.nexa-tab`).forEach(e=>{e.addEventListener(`click`,()=>{this.panel.querySelectorAll(`.nexa-tab`).forEach(e=>e.classList.remove(`nexa-tab-active`)),this.panel.querySelectorAll(`.nexa-panel`).forEach(e=>e.classList.remove(`nexa-panel-active`)),e.classList.add(`nexa-tab-active`),this.panel.querySelector(`[data-panel="${e.dataset.tab}"]`)?.classList.add(`nexa-panel-active`),e.dataset.tab===`metrics`&&this.renderMetrics()})}))}render(){!this.panel||!this.visible||(this.renderMetricsBar(),this.renderRequestList())}renderMetricsBar(){let e=this.tracker.getMetrics(),t=this.panel;t&&(t.querySelector(`[data-metric="total"]`).textContent=String(e.totalRequests),t.querySelector(`[data-metric="avg"]`).textContent=`${e.avgDuration.toFixed(0)}ms`,t.querySelector(`[data-metric="rate"]`).textContent=`${e.requestsPerSecond.toFixed(1)}`,t.querySelector(`[data-metric="success"]`).textContent=String(e.successfulRequests),t.querySelector(`[data-metric="fail"]`).textContent=String(e.failedRequests),t.querySelector(`[data-count="requests"]`).textContent=String(e.totalRequests))}renderRequestList(){let e=this.panel?.querySelector(`.nexa-request-list`);if(!e)return;let t=this.tracker.getHistory();if(this.searchQuery&&(t=t.filter(e=>e.url.toLowerCase().includes(this.searchQuery)||e.method.toLowerCase().includes(this.searchQuery)||String(e.status).includes(this.searchQuery))),t.length===0){e.innerHTML=`
         <div class="nexa-empty">
           <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
             <circle cx="12" cy="12" r="10"/><path d="M8 12h8M12 8v8"/>
@@ -459,5 +458,5 @@ Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=e=>({ok
           <h3>Headers</h3>
           <pre class="nexa-code">${this.formatJson(e.headers)}</pre>
         </div>
-      `:``}`)}showMainView(){let e=this.panel?.querySelector(`.nexa-body`),t=this.panel?.querySelector(`.nexa-detail`);e&&(e.style.display=`flex`),t&&(t.style.display=`none`),this.selectedRequest=null}retrySelected(){if(!this.selectedRequest)return;let{method:e,url:t,body:n,headers:r}=this.selectedRequest;fetch(t,{method:e,headers:r,body:n?JSON.stringify(n):void 0}).then(async e=>{this.selectedRequest&&(this.selectedRequest={...this.selectedRequest,status:e.status,ok:e.ok,duration:this.selectedRequest.duration,timestamp:Date.now()},this.showDetail(this.selectedRequest))}).catch(()=>{})}truncateUrl(e,t=35){try{let t=new URL(e);return t.pathname+(t.search||``)}catch{return e.length>t?e.slice(0,t)+`...`:e}}formatJson(e){try{return JSON.stringify(e,null,2)}catch{return String(e)}}},Q=null,$=null;function be(e={}){return Q?{tracker:$,ui:Q}:($=new J(e),Q=new ye($),Q.show(),{tracker:$,ui:Q})}function xe(){return{tracker:$,ui:Q}}function Se(){Q?.destroy(),Q=null,$=null}exports.AggressiveRetry=d,exports.CachePlugin=P,exports.CacheStore=v,exports.CircuitBreakerRetry=p,exports.ConservativeRetry=f,exports.DedupePlugin=F,exports.Defer=se,exports.Err=t,exports.HttpClient=V,exports.HttpError=H,exports.LoggerPlugin=ue,exports.MetricsPlugin=N,exports.MiddlewarePipeline=ie,exports.Ok=e,exports.PluginManager=M,exports.RequestDeduplicator=x,exports.RequestTracker=J,exports.TypedObservable=D,exports.cacheMiddleware=b,exports.createApiUrl=oe,exports.createCacheMiddleware=y,exports.createDedupeMiddleware=S,exports.createDevOverlay=be,exports.createHttpClient=de,exports.createPipeline=C,exports.createProjectionTransformer=l,exports.createRealtimePlugin=ve,exports.createRequiredFieldsValidator=r,exports.createSSEClient=ge,exports.createSchemaValidator=n,exports.createStreamingMiddleware=j,exports.createTypeGuard=ae,exports.createTypedApiClient=E,exports.createTypedRequest=T,exports.createTypedResponse=w,exports.createUrl=O,exports.createWebSocketClient=me,exports.createWrapperTransformer=u,exports.dedupeMiddleware=re,exports.destroyDevOverlay=Se,exports.getDevOverlay=xe,exports.handleStream=k,exports.isHttpError=U,exports.retry=_,exports.streamToFile=ce,exports.streamingMiddleware=le,exports.transformCamelToSnake=s,exports.transformFlatten=c,exports.transformSnakeToCamel=o,exports.validatorIsArray=i,exports.validatorIsObject=a,exports.withTimeout=ne;
+      `:``}`)}showMainView(){let e=this.panel?.querySelector(`.nexa-body`),t=this.panel?.querySelector(`.nexa-detail`);e&&(e.style.display=`flex`),t&&(t.style.display=`none`),this.selectedRequest=null}retrySelected(){if(!this.selectedRequest)return;let{method:e,url:t,body:n,headers:r}=this.selectedRequest;fetch(t,{method:e,headers:r,body:n?JSON.stringify(n):void 0}).then(async e=>{this.selectedRequest&&(this.selectedRequest={...this.selectedRequest,status:e.status,ok:e.ok,duration:this.selectedRequest.duration,timestamp:Date.now()},this.showDetail(this.selectedRequest))}).catch(()=>{})}truncateUrl(e,t=35){try{let t=new URL(e);return t.pathname+(t.search||``)}catch{return e.length>t?e.slice(0,t)+`...`:e}}formatJson(e){try{return JSON.stringify(e,null,2)}catch{return String(e)}}canUseDOM(){return typeof document<`u`&&typeof document.createElement==`function`&&!!document.body}},Q=null,$=null;function be(e={}){return Q?{tracker:$,ui:Q}:($=new J(e),Q=new ye($),Q.show(),{tracker:$,ui:Q})}function xe(){return{tracker:$,ui:Q}}function Se(){Q?.destroy(),Q=null,$=null}exports.AggressiveRetry=d,exports.CachePlugin=P,exports.CacheStore=v,exports.CircuitBreakerRetry=p,exports.ConservativeRetry=f,exports.DedupePlugin=F,exports.Defer=se,exports.Err=t,exports.HttpClient=V,exports.HttpError=H,exports.LoggerPlugin=ue,exports.MetricsPlugin=N,exports.MiddlewarePipeline=ie,exports.Ok=e,exports.PluginManager=M,exports.RequestDeduplicator=x,exports.RequestTracker=J,exports.TypedObservable=D,exports.cacheMiddleware=b,exports.createApiUrl=oe,exports.createCacheMiddleware=y,exports.createDedupeMiddleware=S,exports.createDevOverlay=be,exports.createHttpClient=de,exports.createPipeline=C,exports.createProjectionTransformer=l,exports.createRealtimePlugin=ve,exports.createRequiredFieldsValidator=r,exports.createSSEClient=ge,exports.createSchemaValidator=n,exports.createStreamingMiddleware=j,exports.createTypeGuard=ae,exports.createTypedApiClient=E,exports.createTypedRequest=T,exports.createTypedResponse=w,exports.createUrl=O,exports.createWebSocketClient=me,exports.createWrapperTransformer=u,exports.dedupeMiddleware=re,exports.destroyDevOverlay=Se,exports.getDevOverlay=xe,exports.handleStream=k,exports.isHttpError=U,exports.retry=_,exports.streamToFile=ce,exports.streamingMiddleware=le,exports.transformCamelToSnake=s,exports.transformFlatten=c,exports.transformSnakeToCamel=o,exports.validatorIsArray=i,exports.validatorIsObject=a,exports.withTimeout=ne;
 //# sourceMappingURL=nexa.cjs.js.map