@nexussdk/tracker 0.0.3 → 0.0.4

package/dist/index.cjs

@@ -1,2 +1,2 @@
-'use strict';var core=require('@nexussdk/core');var T=/^(password|passwd|token|secret|authorization|bearer|auth|credit_?card|cvv|cvc|ssn|api_?key|access_?token|refresh_?token)$/i,C=/\b(?:\d[ -]*?){13,16}\b/g,R=/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,y=/([?&](token|auth|key|secret|password|api_key|access_token|refresh_token)=)[^&]*/gi;function A(n){return n.replace(C,"[CARD_REDACTED]").replace(R,"[EMAIL_REDACTED]").replace(y,"$1[REDACTED]")}function s(n,e=0){if(e>5)return "[MaxDepthExceeded]";if(n==null)return n;if(typeof n=="string")return A(n);if(typeof n!="object")return n;if(Array.isArray(n))return n.map(r=>s(r,e+1));let t={};for(let[r,o]of Object.entries(n))T.test(r)?t[r]="[REDACTED]":t[r]=s(o,e+1);return t}function l(n){return n.replace(y,"$1[REDACTED]")}function f(n){if(!n)return [];let e=[],t=n.split(`
-`);for(let r of t){let o=r.trim(),i=o.match(/^at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)$/)||o.match(/^at\s+(.+?):(\d+):(\d+)$/)||o.match(/^at\s+\((.+?):(\d+):(\d+)\)$/);if(i){i.length===5?e.push({functionName:i[1]??"<anonymous>",fileName:i[2]??"<unknown>",lineNumber:parseInt(i[3]??"0",10),columnNumber:parseInt(i[4]??"0",10)}):i.length===4&&e.push({functionName:"<anonymous>",fileName:i[1]??"<unknown>",lineNumber:parseInt(i[2]??"0",10),columnNumber:parseInt(i[3]??"0",10)});continue}let a=o.match(/^(.+?)@(.+?):(\d+):(\d+)$/);a&&e.push({functionName:a[1]??"<anonymous>",fileName:a[2]??"<unknown>",lineNumber:parseInt(a[3]??"0",10),columnNumber:parseInt(a[4]??"0",10)});}return e}function g(n,e,t){let r=t?.fileName??"unknown",o=t?.lineNumber??0,i=`${n}:${e}:${r}:${o}`,a=5381;for(let d=0;d<i.length;d++)a=(a<<5)+a+i.charCodeAt(d)>>>0;return `fp_${a.toString(16).padStart(8,"0")}`}var c=class{buffer;listenersAttached=false;clickHandler;popStateHandler;constructor(e){this.buffer=new core.RingBuffer(e),this.clickHandler=this.handleClick.bind(this),this.popStateHandler=this.handleNavigation.bind(this);}push(e){let t=e.data?s(e.data):void 0;this.buffer.push({...e,data:t,timestamp:Date.now()});}getAll(){return this.buffer.toArray()}clear(){this.buffer.clear();}attachListeners(){this.listenersAttached||typeof window>"u"||(this.listenersAttached=true,document.addEventListener("click",this.clickHandler,{capture:true,passive:true}),window.addEventListener("popstate",this.popStateHandler,{passive:true}),this.interceptConsoleError());}detachListeners(){!this.listenersAttached||typeof window>"u"||(document.removeEventListener("click",this.clickHandler,{capture:true}),window.removeEventListener("popstate",this.popStateHandler),this.listenersAttached=false);}handleClick(e){let t=e.target;if(!t||t instanceof HTMLInputElement&&(t.type==="password"||t.hasAttribute("data-nexus-mask")))return;let r=this.describeElement(t);this.push({category:"ui.click",message:`Clicked ${r}`,level:"info",data:{elementTag:t.tagName.toLowerCase(),elementId:t.id||void 0,elementClass:t.className||void 0}});}handleNavigation(){this.push({category:"navigation",message:`Navigated to ${l(window.location.href)}`,level:"info",data:{url:l(window.location.href)}});}describeElement(e){let t=[e.tagName.toLowerCase()];return e.id&&t.push(`#${e.id}`),e.getAttribute("aria-label")&&t.push(`[aria-label="${e.getAttribute("aria-label")}"]`),t.join("")}interceptConsoleError(){let e=console.error.bind(console);console.error=(...t)=>{this.push({category:"console",message:t.map(String).join(" ").substring(0,500),level:"error"}),e(...t);};}};var u=class{options;maxRetries;isPageHiding=false;constructor(e){this.options=e,this.maxRetries=e.maxRetries??2,typeof document<"u"&&document.addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"&&(this.isPageHiding=true);}),typeof window<"u"&&window.addEventListener("pagehide",()=>{this.isPageHiding=true;});}send(e){let t=core.safeStringify(e);if(this.isPageHiding&&typeof navigator<"u"&&typeof navigator.sendBeacon=="function"){let r=new Blob([t],{type:"application/json"});navigator.sendBeacon(this.options.endpoint,r);return}this.sendWithRetry(t,0);}async flush(e){let t=core.safeStringify(e);if(typeof navigator<"u"&&typeof navigator.sendBeacon=="function"){let r=new Blob([t],{type:"application/json"});navigator.sendBeacon(this.options.endpoint,r);return}await this.sendWithRetry(t,0);}async sendWithRetry(e,t){try{let r=await fetch(this.options.endpoint,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.options.apiKey}`},body:e,keepalive:!0});if(r.ok)return;if(r.status>=500&&t<this.maxRetries){let o=core.computeBackoffMs(t,1e3,3e4);await new Promise(i=>setTimeout(i,o)),await this.sendWithRetry(e,t+1);}}catch{if(t<this.maxRetries){let r=core.computeBackoffMs(t,1e3,3e4);await new Promise(o=>setTimeout(o,r)),await this.sendWithRetry(e,t+1);}}}};function w(n){if(typeof window>"u")return ()=>{};let e=r=>{let o=r.error instanceof Error?r.error:new Error(r.message);n.captureError(o);},t=r=>{n.captureError(r.reason);};return window.addEventListener("error",e),window.addEventListener("unhandledrejection",t),()=>{window.removeEventListener("error",e),window.removeEventListener("unhandledrejection",t);}}var h=class{apiKey;environment;tags;beforeSend;breadcrumbManager;transport;userContext;dedupeMap=new Map;cleanupListeners;constructor(e={}){this.apiKey=core.resolveApiKey(e.apiKey);let t=core.resolveBaseUrl(e.baseUrl);this.environment=e.environment??"production",this.tags={...e.tags},this.beforeSend=e.beforeSend,this.breadcrumbManager=new c(Math.min(e.maxBreadcrumbs??20,50)),this.transport=new u({endpoint:`${t}/api/v1/telemetry/errors`,apiKey:this.apiKey}),e.autoCapture!==false&&typeof window<"u"&&(this.breadcrumbManager.attachListeners(),this.cleanupListeners=w(this));}captureError(e,t){let r=this.normalizeError(e),o=f(r.stack),i=g(r.type,r.message,o[0]),a=this.dedupeMap.get(i);if(a){a.count+=1;return}let d={fingerprint:i,errorType:r.type,errorMessage:r.message,stackTrace:o,breadcrumbs:this.breadcrumbManager.getAll(),userContext:this.userContext,deviceContext:this.getDeviceContext(),tags:{environment:this.environment,...this.tags,...t},occurrenceCount:1,clientTimestamp:Date.now()},v=s(d),m=this.beforeSend?this.beforeSend(v):v;if(!m)return;this.transport.send(m);let k=setTimeout(()=>{let p=this.dedupeMap.get(i);if(p&&p.count>1){let x={...p.lastPayload,occurrenceCount:p.count,clientTimestamp:Date.now()};this.transport.send(x);}this.dedupeMap.delete(i);},1e4);this.dedupeMap.set(i,{timer:k,count:1,lastPayload:m});}addBreadcrumb(e){this.breadcrumbManager.push(e);}setUser(e){this.userContext=e??void 0;}setTag(e,t){this.tags[e]=t;}async flush(){for(let[e,t]of this.dedupeMap.entries()){if(clearTimeout(t.timer),t.count>0){let r={...t.lastPayload,occurrenceCount:t.count,clientTimestamp:Date.now()};await this.transport.flush(r);}this.dedupeMap.delete(e);}}destroy(){this.cleanupListeners?.(),this.breadcrumbManager.detachListeners(),this.breadcrumbManager.clear(),this.dedupeMap.forEach(e=>clearTimeout(e.timer)),this.dedupeMap.clear();}normalizeError(e){return e instanceof Error?{type:e.name||"Error",message:e.message,stack:e.stack}:typeof e=="string"?{type:"UnhandledException",message:e}:{type:"NonErrorRejection",message:String(e)}}getDeviceContext(){let e=typeof window<"u"&&typeof navigator<"u";return {userAgent:e?navigator.userAgent:"Node/SSR",currentUrl:e?window.location.href:"",viewport:e?`${window.innerWidth}x${window.innerHeight}`:void 0,timezone:Intl?.DateTimeFormat()?.resolvedOptions()?.timeZone,networkStatus:e&&"connection"in navigator?navigator.connection?.effectiveType??"unknown":void 0}}};exports.BreadcrumbManager=c;exports.NexusTrackerClient=h;exports.Transport=u;exports.computeFingerprint=g;exports.parseStackTrace=f;exports.sanitizeObject=s;exports.sanitizeUrl=l;
+'use strict';var core=require('@nexussdk/core');var _=/^(password|passwd|token|secret|authorization|bearer|auth|credit_?card|cvv|cvc|ssn|api_?key|access_?token|refresh_?token)$/i,I=/\b(?:\d[ -]*?){13,16}\b/g,L=/[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g,C=/([?&](token|auth|key|secret|password|api_key|access_token|refresh_token)=)[^&]*/gi;function R(i){return i.replace(I,"[CARD_REDACTED]").replace(L,"[EMAIL_REDACTED]").replace(C,"$1[REDACTED]")}function u(i,e=0){if(e>5)return "[MaxDepthExceeded]";if(i==null)return i;if(typeof i=="string")return R(i);if(typeof i!="object")return i;if(Array.isArray(i))return i.map(t=>u(t,e+1));let r={};for(let[t,n]of Object.entries(i))_.test(t)?r[t]="[REDACTED]":r[t]=u(n,e+1);return r}function b(i){return i.replace(C,"$1[REDACTED]")}function p(i){if(!i)return [];let e=[],r=i.split(`
+`);for(let t of r){let n=t.trim(),o=n.match(/^at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)$/)||n.match(/^at\s+(.+?):(\d+):(\d+)$/)||n.match(/^at\s+\((.+?):(\d+):(\d+)\)$/);if(o){o.length===5?e.push({functionName:o[1]??"<anonymous>",fileName:o[2]??"<unknown>",lineNumber:parseInt(o[3]??"0",10),columnNumber:parseInt(o[4]??"0",10)}):o.length===4&&e.push({functionName:"<anonymous>",fileName:o[1]??"<unknown>",lineNumber:parseInt(o[2]??"0",10),columnNumber:parseInt(o[3]??"0",10)});continue}let s=n.match(/^(.+?)@(.+?):(\d+):(\d+)$/);s&&e.push({functionName:s[1]??"<anonymous>",fileName:s[2]??"<unknown>",lineNumber:parseInt(s[3]??"0",10),columnNumber:parseInt(s[4]??"0",10)});}return e}function f(i,e,r){let t=r?.fileName??"unknown",n=r?.lineNumber??0,o=`${i}:${e}:${t}:${n}`,s=5381;for(let c=0;c<o.length;c++)s=(s<<5)+s+o.charCodeAt(c)>>>0;return `fp_${s.toString(16).padStart(8,"0")}`}var m=class{buffer;listenersAttached=false;clickHandler;popStateHandler;constructor(e){this.buffer=new core.RingBuffer(e),this.clickHandler=this.handleClick.bind(this),this.popStateHandler=this.handleNavigation.bind(this);}push(e){let r=e.data?u(e.data):void 0;this.buffer.push({...e,data:r,timestamp:Date.now()});}getAll(){return this.buffer.toArray()}clear(){this.buffer.clear();}attachListeners(){this.listenersAttached||typeof window>"u"||(this.listenersAttached=true,document.addEventListener("click",this.clickHandler,{capture:true,passive:true}),window.addEventListener("popstate",this.popStateHandler,{passive:true}),this.interceptConsoleError());}detachListeners(){!this.listenersAttached||typeof window>"u"||(document.removeEventListener("click",this.clickHandler,{capture:true}),window.removeEventListener("popstate",this.popStateHandler),this.listenersAttached=false);}handleClick(e){let r=e.target;if(!r||r instanceof HTMLInputElement&&(r.type==="password"||r.hasAttribute("data-nexus-mask")))return;let t=this.describeElement(r);this.push({category:"ui.click",message:`Clicked ${t}`,level:"info",data:{elementTag:r.tagName.toLowerCase(),elementId:r.id||void 0,elementClass:r.className||void 0}});}handleNavigation(){this.push({category:"navigation",message:`Navigated to ${b(window.location.href)}`,level:"info",data:{url:b(window.location.href)}});}describeElement(e){let r=[e.tagName.toLowerCase()];return e.id&&r.push(`#${e.id}`),e.getAttribute("aria-label")&&r.push(`[aria-label="${e.getAttribute("aria-label")}"]`),r.join("")}interceptConsoleError(){let e=console.error.bind(console);console.error=(...r)=>{this.push({category:"console",message:r.map(String).join(" ").substring(0,500),level:"error"}),e(...r);};}};var k="nexus_events",x=200,g=class{options;maxRetries;plugin;isPageHiding=false;constructor(e){this.options=e,this.maxRetries=e.maxRetries??2,this.plugin=e.plugin??"fetch",this.plugin==="fetch"&&(typeof document<"u"&&document.addEventListener("visibilitychange",()=>{document.visibilityState==="hidden"&&(this.isPageHiding=true);}),typeof window<"u"&&window.addEventListener("pagehide",()=>{this.isPageHiding=true;}));}send(e){if(typeof this.plugin=="function"){this.plugin(e);return}switch(this.plugin){case "console":this.sendConsole(e);return;case "localStorage":this.sendLocalStorage(e);return;default:this.sendFetch(e);}}async flush(e){if(typeof this.plugin=="function"){await this.plugin(e);return}switch(this.plugin){case "console":this.sendConsole(e);return;case "localStorage":this.sendLocalStorage(e);return;default:{let r=core.safeStringify(e);if(typeof navigator<"u"&&typeof navigator.sendBeacon=="function"){let t=new Blob([r],{type:"application/json"});navigator.sendBeacon(this.options.endpoint,t);return}await this.sendWithRetry(r,0);}}}sendFetch(e){let r=core.safeStringify(e);if(this.isPageHiding&&typeof navigator<"u"&&typeof navigator.sendBeacon=="function"){let t=new Blob([r],{type:"application/json"});navigator.sendBeacon(this.options.endpoint,t);return}this.sendWithRetry(r,0);}sendConsole(e){let r=`[Nexus|${e.errorType}]`;console.group(r,e.errorMessage),console.warn("Fingerprint:",e.fingerprint),console.warn("Stack frames:",e.stackTrace.slice(0,3)),e.breadcrumbs.length>0&&console.warn("Last breadcrumbs:",e.breadcrumbs.slice(-5)),e.userContext&&console.warn("User:",e.userContext),console.groupEnd();}sendLocalStorage(e){if(!(typeof localStorage>"u"))try{let r=localStorage.getItem(k),t=r?JSON.parse(r):[];t.push(e),t.length>x&&t.splice(0,t.length-x),localStorage.setItem(k,core.safeStringify(t));}catch{}}async sendWithRetry(e,r){try{let t=await fetch(this.options.endpoint,{method:"POST",headers:{"Content-Type":"application/json",Authorization:`Bearer ${this.options.apiKey}`},body:e,keepalive:!0});if(t.ok)return;if(t.status>=500&&r<this.maxRetries){let n=core.computeBackoffMs(r,1e3,3e4);await new Promise(o=>setTimeout(o,n)),await this.sendWithRetry(e,r+1);}}catch{if(r<this.maxRetries){let t=core.computeBackoffMs(r,1e3,3e4);await new Promise(n=>setTimeout(n,t)),await this.sendWithRetry(e,r+1);}}}};function S(i){if(typeof window>"u")return ()=>{};let e=t=>{let n=t.error instanceof Error?t.error:new Error(t.message);i.captureError(n);},r=t=>{i.captureError(t.reason);};return window.addEventListener("error",e),window.addEventListener("unhandledrejection",r),()=>{window.removeEventListener("error",e),window.removeEventListener("unhandledrejection",r);}}var w=class{apiKey;environment;tags;extras;beforeSend;breadcrumbManager;transport;samplingRate;dedupeWindowMs;maxPerSession;sessionCaptureCount=0;userContext;dedupeMap=new Map;cleanupListeners;constructor(e={}){this.apiKey=core.resolveApiKey(e.apiKey);let r=core.resolveBaseUrl(e.baseUrl);this.environment=e.environment??"production",this.tags={...e.tags},this.extras={},this.beforeSend=e.beforeSend,this.samplingRate=Math.max(0,Math.min(1,e.sampling?.rate??1)),this.dedupeWindowMs=e.sampling?.dedupeWindow??1e4,this.maxPerSession=e.sampling?.maxPerSession??100,this.breadcrumbManager=new m(Math.min(e.maxBreadcrumbs??20,50)),this.transport=new g({endpoint:`${r}/api/v1/telemetry/errors`,apiKey:this.apiKey,plugin:e.transport}),e.autoCapture!==false&&typeof window<"u"&&(this.breadcrumbManager.attachListeners(),this.cleanupListeners=S(this));}captureError(e,r){if(this.sessionCaptureCount>=this.maxPerSession||this.samplingRate<1&&Math.random()>this.samplingRate)return;let t=this.normalizeError(e),n=p(t.stack),o=f(t.type,t.message,n[0]),s=this.dedupeMap.get(o);if(s){s.count+=1;return}let c={fingerprint:o,errorType:t.type,errorMessage:t.message,stackTrace:n,breadcrumbs:this.breadcrumbManager.getAll(),userContext:this.userContext,deviceContext:this.getDeviceContext(),tags:{environment:this.environment,...this.tags,...r},occurrenceCount:1,clientTimestamp:Date.now()},l=u(c),a=this.beforeSend?this.beforeSend(l):l;if(!a)return;this.transport.send(a),this.sessionCaptureCount++;let h=setTimeout(()=>{let y=this.dedupeMap.get(o);if(y&&y.count>1){let N={...y.lastPayload,occurrenceCount:y.count,clientTimestamp:Date.now()};this.transport.send(N);}this.dedupeMap.delete(o);},this.dedupeWindowMs);this.dedupeMap.set(o,{timer:h,count:1,lastPayload:a});}captureMessage(e,r="info",t){let n=new Error(e);n.name="NexusMessage",this.captureError(n,{_level:r,...t});}addBreadcrumb(e){this.breadcrumbManager.push(e);}setUser(e){this.userContext=e??void 0;}setTag(e,r){this.tags[e]=r;}setExtra(e,r){this.extras[e]=r;}async flush(){for(let[e,r]of this.dedupeMap.entries()){if(clearTimeout(r.timer),r.count>0){let t={...r.lastPayload,occurrenceCount:r.count,clientTimestamp:Date.now()};await this.transport.flush(t);}this.dedupeMap.delete(e);}}destroy(){this.cleanupListeners?.(),this.breadcrumbManager.detachListeners(),this.breadcrumbManager.clear(),this.dedupeMap.forEach(e=>clearTimeout(e.timer)),this.dedupeMap.clear();}normalizeError(e){return e instanceof Error?{type:e.name||"Error",message:e.message,stack:e.stack}:typeof e=="string"?{type:"UnhandledException",message:e}:{type:"NonErrorRejection",message:String(e)}}getDeviceContext(){let e=typeof window<"u"&&typeof navigator<"u";return {userAgent:e?navigator.userAgent:"Node/SSR",currentUrl:e?window.location.href:"",viewport:e?`${window.innerWidth}x${window.innerHeight}`:void 0,timezone:Intl?.DateTimeFormat()?.resolvedOptions()?.timeZone,networkStatus:e&&"connection"in navigator?navigator.connection?.effectiveType??"unknown":void 0}}};var T=class{_error=null;_errorInfo=null;_listeners=new Set;_tracker;_onError;_tags;_generateErrorId;constructor(e={}){this._tracker=e.tracker,this._onError=e.onError,this._tags=e.tags,this._generateErrorId=e.generateErrorId??(r=>{let t=p(r.stack);return `NX-${f(r.name,r.message,t[0]).replace(/^fp_/,"").slice(0,8).toUpperCase()}`});}get hasError(){return this._error!==null}get currentError(){return this._error}get errorInfo(){return this._errorInfo}capture(e,r){let t=e instanceof Error?e:new Error(String(e));this._error=t;let n=this._generateErrorId(t),o={error:t,errorId:n,reset:()=>this.recover(),componentStack:r?.componentStack};if(this._errorInfo=o,this._tracker)try{this._tracker.captureError(t,{tags:{...this._tags,...r?.tags,guardErrorId:n},componentStack:r?.componentStack});}catch(s){typeof console<"u"&&console.warn("[NexusGuardCore] Failed to forward error to tracker:",s);}if(this._onError)try{this._onError(t,o);}catch(s){typeof console<"u"&&console.warn("[NexusGuardCore] onError callback threw:",s);}return this._notify(),o}recover(){this._error!==null&&(this._error=null,this._errorInfo=null,this._notify());}reset(){this.recover();}subscribe(e){return this._listeners.add(e),e(this._errorInfo),()=>{this._listeners.delete(e);}}_notify(){for(let e of this._listeners)try{e(this._errorInfo);}catch(r){typeof console<"u"&&console.error("[NexusGuardCore] Subscriber threw error:",r);}}};var F={LCP:[2500,4e3],CLS:[.1,.25],FID:[100,300],TTFB:[800,1800],INP:[200,500],FCP:[1800,3e3]};function d(i,e){let[r,t]=F[i]??[1/0,1/0];return e<=r?"good":e<=t?"needs-improvement":"poor"}function v(){return typeof performance>"u"?"navigate":performance.getEntriesByType("navigation")[0]?.type??"navigate"}function B(i){if(typeof PerformanceObserver>"u")return ()=>{};let e=0,r=null;try{r=new PerformanceObserver(o=>{let s=o.getEntries(),c=s[s.length-1];if(!c)return;e=c.startTime??0;}),r.observe({type:"largest-contentful-paint",buffered:!0});}catch{return ()=>{}}let t=()=>{e!==0&&i({name:"LCP",value:e,rating:d("LCP",e),delta:e,navigationType:v()});},n=()=>t();return document.addEventListener("visibilitychange",n,{once:true}),()=>{r?.disconnect(),document.removeEventListener("visibilitychange",n);}}function D(i){if(typeof PerformanceObserver>"u")return ()=>{};let e=0,r=null;try{r=new PerformanceObserver(o=>{for(let s of o.getEntries()){let c=s;c.hadRecentInput||(e+=c.value??0);}}),r.observe({type:"layout-shift",buffered:!0});}catch{return ()=>{}}let t=()=>{e!==0&&i({name:"CLS",value:e,rating:d("CLS",e),delta:e,navigationType:v()});},n=()=>t();return document.addEventListener("visibilitychange",n,{once:true}),()=>{r?.disconnect(),document.removeEventListener("visibilitychange",n);}}function $(i){if(typeof PerformanceObserver>"u")return ()=>{};let e=null;try{e=new PerformanceObserver(r=>{let n=r.getEntries()[0];if(!n)return;let o=n.processingStart-n.startTime;i({name:"FID",value:o,rating:d("FID",o),delta:o,navigationType:v()}),e?.disconnect();}),e.observe({type:"first-input",buffered:!0});}catch{return ()=>{}}return ()=>e?.disconnect()}function V(i){if(typeof PerformanceObserver>"u")return ()=>{};try{let r=performance.getEntriesByType("navigation")[0];if(r){let t=r.responseStart-r.requestStart;i({name:"TTFB",value:t,rating:d("TTFB",t),delta:t,navigationType:r.type??"navigate"});}}catch{}return ()=>{}}function H(i){if(typeof PerformanceObserver>"u")return ()=>{};let e=0,r=null;try{r=new PerformanceObserver(o=>{for(let s of o.getEntries()){let c=s;c.duration>e&&(e=c.duration);}}),r.observe({type:"event",buffered:!0,durationThreshold:16});}catch{return ()=>{}}let t=()=>{e!==0&&i({name:"INP",value:e,rating:d("INP",e),delta:e,navigationType:v()});},n=()=>t();return document.addEventListener("visibilitychange",n,{once:true}),()=>{r?.disconnect(),document.removeEventListener("visibilitychange",n);}}function j(i){if(typeof PerformanceObserver>"u")return ()=>{};let e=null;try{e=new PerformanceObserver(r=>{let n=r.getEntries().find(s=>s.name==="first-contentful-paint");if(!n)return;let o=n.startTime;i({name:"FCP",value:o,rating:d("FCP",o),delta:o,navigationType:v()}),e?.disconnect();}),e.observe({type:"paint",buffered:!0});}catch{return ()=>{}}return ()=>e?.disconnect()}function z(i,e){if(typeof PerformanceObserver>"u")return ()=>{};let r=null;try{r=new PerformanceObserver(t=>{for(let n of t.getEntries())n.duration>=e&&i.addBreadcrumb({category:"custom",message:`Long task detected: ${Math.round(n.duration)}ms`,level:n.duration>=e*3?"error":"warning",data:{durationMs:Math.round(n.duration),startTime:Math.round(n.startTime)}});}),r.observe({type:"longtask",buffered:!0});}catch{return ()=>{}}return ()=>r?.disconnect()}var U={LCP:B,CLS:D,FID:$,TTFB:V,INP:H,FCP:j};function W(i,e={}){if(typeof window>"u")return ()=>{};let{captureAsEvents:r=false,poorRatingOnly:t=false,vitals:n=["LCP","CLS","FID","TTFB","INP","FCP"],longTaskThresholdMs:o=50}=e,s=a=>{t&&a.rating==="good"||(i.addBreadcrumb({category:"custom",message:`Web Vital ${a.name}: ${a.rating.toUpperCase()} (${Math.round(a.value)}${a.name==="CLS"?"":"ms"})`,level:a.rating==="poor"?"error":a.rating==="needs-improvement"?"warning":"info",data:{metric:a.name,value:a.value,rating:a.rating,navigationType:a.navigationType}}),r&&a.rating!=="good"&&i.captureMessage(`Performance degradation: ${a.name} is ${a.rating} (${Math.round(a.value)}${a.name==="CLS"?"":"ms"})`,a.rating==="poor"?"error":"warning",{metric:a.name,value:a.value,rating:a.rating,navigationType:a.navigationType}));},c=n.map(a=>{let h=U[a];return h?h(s):()=>{}}),l=z(i,o);return ()=>{c.forEach(a=>a()),l();}}exports.BreadcrumbManager=m;exports.NexusGuardCore=T;exports.NexusTrackerClient=w;exports.Transport=g;exports.attachWebVitals=W;exports.computeFingerprint=f;exports.parseStackTrace=p;exports.sanitizeObject=u;exports.sanitizeUrl=b;

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { Breadcrumb, UserContext, ErrorEventPayload, StackFrame } from '@nexussdk/contracts';
+import { SeverityLevel, Breadcrumb, UserContext, ErrorEventPayload, SamplingConfig, TransportPlugin, StackFrame, NexusErrorInfo, PerformanceVitalsOptions } from '@nexussdk/contracts';
 
 /**
  * @fileoverview NexusTrackerClient — Full-featured crash ingestion and telemetry SDK.
- * Automated global error capture, PII sanitization, deduplication, and hybrid transport.
+ * Automated global error capture, PII sanitization, deduplication, sampling, and hybrid transport.
  * @module @nexus/sdk-tracker/client
  */
 
@@ -15,6 +15,8 @@ import { Breadcrumb, UserContext, ErrorEventPayload, StackFrame } from '@nexussd
  *   environment: 'production',
  *   autoCapture: true,
  *   maxBreadcrumbs: 20,
+ *   sampling: { rate: 0.5, dedupeWindow: 5000 },
+ *   transport: 'console', // development mode
  * });
  */
 interface NexusTrackerOptions {
@@ -29,10 +31,12 @@ interface NexusTrackerOptions {
     baseUrl?: string;
     /**
      * Target deployment environment ('production' | 'staging' | 'development').
+     * @default 'production'
      */
     environment?: string;
     /**
      * Max breadcrumbs retained in ring buffer. Defaults to 20 (max 50).
+     * @default 20
      */
     maxBreadcrumbs?: number;
     /**
@@ -41,13 +45,39 @@ interface NexusTrackerOptions {
     tags?: Record<string, string>;
     /**
      * Toggle automated capturing of uncaught exceptions. Defaults to true.
+     * @default true
      */
     autoCapture?: boolean;
     /**
      * Callback hook to inspect, mutate, or drop an event before dispatch.
      * Return null to drop the event completely.
+     *
+     * @example
+     * beforeSend: (event) => {
+     *   if (event.tags?.environment === 'test') return null; // drop test events
+     *   return event;
+     * }
      */
     beforeSend?: (event: ErrorEventPayload) => ErrorEventPayload | null;
+    /**
+     * Client-side event sampling and rate limiting configuration.
+     *
+     * @example
+     * sampling: { rate: 0.5, dedupeWindow: 5000, maxPerSession: 25 }
+     */
+    sampling?: SamplingConfig;
+    /**
+     * Transport plugin for event delivery.
+     * - `'fetch'` (default) — HTTP POST to ingestion endpoint
+     * - `'console'` — log to browser console (development)
+     * - `'localStorage'` — buffer events in localStorage
+     * - `Function` — custom async handler
+     *
+     * @example
+     * transport: 'console'
+     * transport: async (event) => await myLogger.log(event)
+     */
+    transport?: TransportPlugin;
 }
 /**
  * Public interface contract for NexusTrackerClient.
@@ -63,6 +93,19 @@ interface INexusTrackerClient {
      * tracker.captureError(new TypeError('Payment failed'), { checkoutStep: 'payment' });
      */
     captureError(error: unknown, extra?: Record<string, unknown>): void;
+    /**
+     * Captures a custom message event (non-exception telemetry).
+     * Useful for business-logic events, warnings, or diagnostic checkpoints.
+     *
+     * @param message - Human-readable message string.
+     * @param level - Severity level. Defaults to 'info'.
+     * @param extra - Optional metadata tags attached to the event.
+     *
+     * @example
+     * tracker.captureMessage('checkout_step_completed', 'info', { step: 3, cartTotal: 129.99 });
+     * tracker.captureMessage('payment_gateway_slow', 'warning', { latencyMs: 4500 });
+     */
+    captureMessage(message: string, level?: SeverityLevel, extra?: Record<string, unknown>): void;
     /**
      * Records a user activity step into the chronological breadcrumb ring buffer.
      *
@@ -83,14 +126,28 @@ interface INexusTrackerClient {
     setUser(user: UserContext | null): void;
     /**
      * Dynamically sets or updates a persistent search tag.
+     * Tags are attached to all subsequent events.
      *
      * @param key - Tag key name.
      * @param value - Tag value string.
      *
      * @example
      * tracker.setTag('app_version', '2.4.1');
+     * tracker.setTag('ab_test', 'variant_b');
      */
     setTag(key: string, value: string): void;
+    /**
+     * Sets an unstructured extra metadata value.
+     * Unlike tags (strings only), extras accept any serializable value.
+     *
+     * @param key - Extra key name.
+     * @param value - Any serializable value (object, number, array, etc.).
+     *
+     * @example
+     * tracker.setExtra('cart_items', 3);
+     * tracker.setExtra('feature_flags', { checkout_v2: true });
+     */
+    setExtra(key: string, value: unknown): void;
     /**
      * Flushes any buffered events immediately via navigator.sendBeacon or fetch.
      *
@@ -116,14 +173,20 @@ interface INexusTrackerClient {
  * @example
  * const tracker = new NexusTrackerClient({ apiKey: 'pk_live_...' });
  * tracker.captureError(new Error('Checkout failed'));
+ * tracker.captureMessage('cart_abandoned', 'warning', { items: 3 });
  */
 declare class NexusTrackerClient implements INexusTrackerClient {
     private readonly apiKey;
     private readonly environment;
     private readonly tags;
+    private readonly extras;
     private readonly beforeSend?;
     private readonly breadcrumbManager;
     private readonly transport;
+    private readonly samplingRate;
+    private readonly dedupeWindowMs;
+    private readonly maxPerSession;
+    private sessionCaptureCount;
     private userContext?;
     private readonly dedupeMap;
     private cleanupListeners?;
@@ -132,6 +195,11 @@ declare class NexusTrackerClient implements INexusTrackerClient {
      * Captures an error exception, generates fingerprint, scrubs PII, and enqueues transmission.
      */
     captureError(error: unknown, extra?: Record<string, unknown>): void;
+    /**
+     * Captures a custom diagnostic message as a synthetic error event.
+     * The errorType is set to 'NexusMessage' with the level encoded in tags.
+     */
+    captureMessage(message: string, level?: SeverityLevel, extra?: Record<string, unknown>): void;
     /**
      * Records a contextual breadcrumb in the ring buffer.
      */
@@ -144,6 +212,10 @@ declare class NexusTrackerClient implements INexusTrackerClient {
      * Sets a custom tag associated with error events.
      */
     setTag(key: string, value: string): void;
+    /**
+     * Sets an unstructured extra metadata value attached to all subsequent events.
+     */
+    setExtra(key: string, value: unknown): void;
     /**
      * Flushes all pending deduplication queues and dispatches queued payloads immediately.
      */
@@ -294,6 +366,7 @@ declare class BreadcrumbManager {
 
 /**
  * @fileoverview Hybrid transport dispatcher for error payload delivery.
+ * Supports pluggable transport: fetch (default), console, localStorage, or custom function.
  * Prefers fetch with keepalive; falls back to navigator.sendBeacon during page unload.
  * @module @nexus/sdk-tracker/transport
  */
@@ -302,54 +375,188 @@ declare class BreadcrumbManager {
  * Options for configuring the transport dispatcher.
  */
 interface TransportOptions {
-    /** Go-Gin ingestion endpoint URL. */
+    /** Go-Gin ingestion endpoint URL. Used only when plugin is 'fetch' (default). */
     endpoint: string;
-    /** Public API key for Authorization header. */
+    /** Public API key for Authorization header. Used only when plugin is 'fetch'. */
     apiKey: string;
-    /** Maximum retry attempts on network failures. Defaults to 2. */
+    /** Maximum retry attempts on network failures. Defaults to 2. Applied to 'fetch' only. */
     maxRetries?: number;
+    /**
+     * Transport plugin selection.
+     * - `'fetch'` (default) — standard HTTP POST to ingestion endpoint with retry
+     * - `'console'` — logs event to console.warn (ideal for development)
+     * - `'localStorage'` — persists event JSON to localStorage under key `nexus_events`
+     * - `Function` — custom async dispatcher; receives the full ErrorEventPayload
+     *
+     * @example
+     * // Development: log to console only
+     * new Transport({ endpoint: '...', apiKey: '...', plugin: 'console' })
+     *
+     * @example
+     * // Custom forwarding transport
+     * new Transport({ endpoint: '...', apiKey: '...', plugin: async (event) => {
+     *   await fetch('/my-logging-endpoint', { method: 'POST', body: JSON.stringify(event) });
+     * }})
+     */
+    plugin?: TransportPlugin;
 }
 /**
  * Hybrid transport dispatcher that intelligently selects the delivery mechanism:
  * - **Normal execution**: `fetch(url, { keepalive: true })` with retry
  * - **Page teardown** (`visibilityState === 'hidden'` or `pagehide`): `navigator.sendBeacon`
+ * - **Plugin override**: delegates entirely to the configured plugin strategy
  *
  * @example
+ * // Default fetch transport
  * const transport = new Transport({
  *   endpoint: 'http://localhost:8080/api/v1/telemetry/errors',
  *   apiKey: 'pk_live_...',
  * });
- * transport.send(errorPayload);
+ *
+ * @example
+ * // Console transport (development)
+ * const transport = new Transport({
+ *   endpoint: 'http://localhost:8080/api/v1/telemetry/errors',
+ *   apiKey: 'pk_dev_...',
+ *   plugin: 'console',
+ * });
  */
 declare class Transport {
     private readonly options;
     private readonly maxRetries;
+    private readonly plugin;
     private isPageHiding;
     constructor(options: TransportOptions);
     /**
-     * Dispatches an error payload to the Go-Gin ingestion endpoint.
-     * Automatically selects fetch or sendBeacon based on page lifecycle state.
+     * Dispatches an error payload via the configured transport plugin.
+     * Automatically selects fetch or sendBeacon when plugin is 'fetch'.
      *
      * @param payload - The sanitized {@link ErrorEventPayload} to transmit.
-     *
-     * @example
-     * transport.send({
-     *   fingerprint: 'fp_abc123',
-     *   errorType: 'TypeError',
-     *   errorMessage: "Cannot read property 'map' of undefined",
-     *   // ...
-     * });
      */
     send(payload: ErrorEventPayload): void;
     /**
-     * Forces immediate flush of all pending events using sendBeacon.
-     * Called during manual flush or SDK destroy lifecycle.
+     * Forces immediate flush of all pending events.
+     * Delegates to the active plugin strategy.
      *
      * @param payload - The error payload to flush.
-     * @returns Promise that resolves when the beacon is dispatched.
      */
     flush(payload: ErrorEventPayload): Promise<void>;
+    private sendFetch;
+    private sendConsole;
+    private sendLocalStorage;
     private sendWithRetry;
 }
 
-export { BreadcrumbManager, type INexusTrackerClient, NexusTrackerClient, type NexusTrackerOptions, Transport, type TransportOptions, computeFingerprint, parseStackTrace, sanitizeObject, sanitizeUrl };
+/**
+ * @fileoverview Framework-agnostic Error Boundary core logic for Nexus SDK.
+ * Encapsulates error capture, fingerprint extraction, recovery state, and subscriber dispatch.
+ * Used directly by Vanilla integrations and underpins React / Vue / Angular adapters.
+ * @module @nexus/sdk-tracker/guard
+ */
+
+interface NexusGuardCoreOptions {
+    /** Tracker client instance used to forward captured errors. Optional. */
+    tracker?: NexusTrackerClient;
+    /** Callback fired immediately upon capturing an unhandled boundary exception. */
+    onError?: (error: Error, info: NexusErrorInfo) => void;
+    /** Static tags attached to all errors captured by this guard instance. */
+    tags?: Record<string, string>;
+    /** Custom error ID generator function. Defaults to computeFingerprint hash. */
+    generateErrorId?: (error: Error) => string;
+}
+/**
+ * Framework-agnostic Error Boundary controller.
+ * Maintains boundary state, generates support reference fingerprints,
+ * notifies listeners, and optionally forwards errors to NexusTrackerClient.
+ *
+ * @example
+ * // Vanilla JS DOM boundary
+ * const guard = new NexusGuardCore({ tracker });
+ * guard.subscribe((info) => {
+ *   if (info) {
+ *     container.innerHTML = `<div>Crash ID: ${info.errorId} <button id="retry">Retry</button></div>`;
+ *     document.getElementById('retry')?.addEventListener('click', () => guard.recover());
+ *   } else {
+ *     renderApp(container);
+ *   }
+ * });
+ */
+declare class NexusGuardCore {
+    private _error;
+    private _errorInfo;
+    private _listeners;
+    private readonly _tracker?;
+    private readonly _onError?;
+    private readonly _tags?;
+    private readonly _generateErrorId;
+    constructor(options?: NexusGuardCoreOptions);
+    /** Whether the guard is currently in an error state. */
+    get hasError(): boolean;
+    /** The captured Error instance, or null if healthy. */
+    get currentError(): Error | null;
+    /** Full normalized error info for rendering fallback UI, or null if healthy. */
+    get errorInfo(): NexusErrorInfo | null;
+    /**
+     * Captures an error thrown within the guarded scope.
+     * Dispatches to subscribers, calls onError callback, and sends to tracker if configured.
+     */
+    capture(error: unknown, context?: {
+        componentStack?: string;
+        tags?: Record<string, string>;
+    }): NexusErrorInfo;
+    /**
+     * Recovers from the error state back to normal execution.
+     * Clears the current error and notifies all subscribers with null.
+     */
+    recover(): void;
+    /** Alias for recover(). */
+    reset(): void;
+    /**
+     * Subscribes to guard state changes (error captured or recovered).
+     * @param listener Callback receiving NexusErrorInfo or null on recovery.
+     * @returns Unsubscribe function.
+     */
+    subscribe(listener: (info: NexusErrorInfo | null) => void): () => void;
+    private _notify;
+}
+
+/**
+ * @fileoverview Web Vitals and Long Task performance observer for the Nexus Tracker.
+ * Captures LCP, CLS, FID, TTFB, INP, FCP as breadcrumbs or full error events.
+ * Uses the native PerformanceObserver API — no external dependencies.
+ * @module @nexus/sdk-tracker/performance
+ */
+
+/**
+ * Attaches Web Vitals observers to the tracker instance.
+ * Records metrics as breadcrumbs (default) or as full error events (when `captureAsEvents: true`).
+ * Also observes long tasks above the configured threshold.
+ *
+ * Must be called in a browser context after `DOMContentLoaded`.
+ * Safe to call in Next.js client components and SPA route entry points.
+ *
+ * @param tracker - The initialized NexusTrackerClient instance.
+ * @param options - Observer configuration.
+ * @returns Cleanup function — call on component unmount or SDK destroy.
+ *
+ * @example
+ * // Record all vitals as breadcrumbs
+ * const cleanup = attachWebVitals(tracker);
+ *
+ * @example
+ * // Record poor vitals as full events with console output
+ * const cleanup = attachWebVitals(tracker, {
+ *   poorRatingOnly: true,
+ *   captureAsEvents: true,
+ *   vitals: ['LCP', 'CLS', 'INP'],
+ * });
+ *
+ * @example
+ * // Next.js App Router — attach in a Client Component effect
+ * useEffect(() => {
+ *   return attachWebVitals(tracker, { poorRatingOnly: true });
+ * }, []);
+ */
+declare function attachWebVitals(tracker: NexusTrackerClient, options?: PerformanceVitalsOptions): () => void;
+
+export { BreadcrumbManager, type INexusTrackerClient, NexusGuardCore, type NexusGuardCoreOptions, NexusTrackerClient, type NexusTrackerOptions, Transport, type TransportOptions, attachWebVitals, computeFingerprint, parseStackTrace, sanitizeObject, sanitizeUrl };