@nexussdk/sdk 0.0.3 → 0.0.4

package/dist/react.d.mts

@@ -1,23 +1,34 @@
 import React from 'react';
-import { NexusFlagsOptions, NexusFlagsClient } from '@nexussdk/flags';
-import { NexusTrackerOptions, NexusTrackerClient } from '@nexussdk/tracker';
-import { UserContext, FlagEvaluationResult } from '@nexussdk/contracts';
+import { NexusFlagsClient, NexusFlagsOptions } from '@nexussdk/flags';
+import { NexusTrackerClient, NexusTrackerOptions } from '@nexussdk/tracker';
+import { UserContext, SamplingConfig, TransportPlugin, PerformanceVitalsOptions, SeverityLevel, Breadcrumb, NexusErrorInfo, FlagEvaluationResult } from '@nexussdk/contracts';
 
 /**
  * @fileoverview Unified Nexus singleton facade wrapping Flags and Tracker clients.
  * @module @nexus/sdk/nexus
  */
 
+/**
+ * Dev server routing configuration.
+ */
+interface NexusDevServerOptions {
+    /** Enable local dev server ingestion mode. Auto-enabled in development if true. */
+    enabled?: boolean;
+    /** Port the dev server is listening on. Defaults to 4567. */
+    port?: number;
+    /** Host the dev server is bound to. Defaults to 'localhost'. */
+    host?: string;
+}
 /**
  * Unified initialization options for the Nexus SDK umbrella.
  *
  * @example
  * Nexus.init({
  *   apiKey: 'pk_live_...',
- *   baseUrl: 'http://localhost:8080',
  *   user: { id: 'usr_12345', country: 'VN' },
  *   environment: 'production',
  *   autoCapture: true,
+ *   devServer: { enabled: process.env.NODE_ENV === 'development' },
  * });
  */
 interface NexusInitOptions {
@@ -33,6 +44,14 @@ interface NexusInitOptions {
     tags?: Record<string, string>;
     /** Toggle automated global error capture. Defaults to true. */
     autoCapture?: boolean;
+    /** Client-side rate limiting and deduplication sampling options. */
+    sampling?: SamplingConfig;
+    /** Pluggable transport adapter ('fetch', 'console', 'localStorage', custom fn). */
+    transport?: TransportPlugin;
+    /** Web Vitals performance observer options, or true for default observation. */
+    vitals?: boolean | PerformanceVitalsOptions;
+    /** Local dev server auto-routing configuration. */
+    devServer?: NexusDevServerOptions;
     /** Additional flags-specific options. */
     flags?: Partial<NexusFlagsOptions>;
     /** Additional tracker-specific options. */
@@ -59,6 +78,7 @@ interface NexusInitOptions {
  */
 declare class Nexus {
     private static instance;
+    private static vitalsCleanup;
     /** The underlying feature flags client instance. */
     readonly flags: NexusFlagsClient;
     /** The underlying error tracker client instance. */
@@ -71,9 +91,6 @@ declare class Nexus {
      *
      * @param options - SDK configuration options.
      * @returns The initialized Nexus singleton instance.
-     *
-     * @example
-     * const nexus = Nexus.init({ apiKey: 'pk_live_...' });
      */
     static init(options?: NexusInitOptions): Nexus;
     /**
@@ -81,73 +98,52 @@ declare class Nexus {
      *
      * @returns The active Nexus instance.
      * @throws {Error} If `Nexus.init()` has not been called yet.
-     *
-     * @example
-     * const nexus = Nexus.getInstance();
-     * nexus.flags.isEnabled('checkout_v2');
      */
     static getInstance(): Nexus;
     /**
      * Convenience method: Check if a feature flag is enabled.
-     *
-     * @param key - Flag identifier.
-     * @param defaultValue - Fallback if flag is missing.
-     * @returns Boolean enabled state.
-     *
-     * @example
-     * if (Nexus.isEnabled('checkout_redesign')) { ... }
      */
     static isEnabled(key: string, defaultValue?: boolean): boolean;
     /**
      * Convenience method: Get a flag variant value.
-     *
-     * @param key - Flag identifier.
-     * @param variantKey - Variant property name.
-     * @param defaultValue - Fallback value.
-     * @returns Variant value cast to type T.
-     *
-     * @example
-     * const rate = Nexus.getVariant<number>('promo_banner_v2', 'discount_rate', 10);
      */
     static getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T;
     /**
      * Convenience method: Capture an error manually.
-     *
-     * @param error - Error instance, string, or unknown value.
-     * @param extra - Optional metadata tags.
-     *
-     * @example
-     * Nexus.captureError(new TypeError('Cannot read properties of null'));
      */
     static captureError(error: unknown, extra?: Record<string, unknown>): void;
+    /**
+     * Convenience method: Capture an informational or warning message event.
+     */
+    static captureMessage(message: string, level?: SeverityLevel, extra?: Record<string, unknown>): void;
+    /**
+     * Convenience method: Add a breadcrumb manually.
+     */
+    static addBreadcrumb(breadcrumb: Breadcrumb): void;
+    /**
+     * Convenience method: Set extra contextual metadata.
+     */
+    static setExtra(key: string, value: unknown): void;
+    /**
+     * Convenience method: Attach Web Vitals observer to tracker.
+     */
+    static attachWebVitals(options?: PerformanceVitalsOptions): () => void;
     /**
      * Convenience method: Update user context for both flags and tracker.
-     *
-     * @param user - New user context (merged with existing).
-     * @returns Promise resolving after flags refresh.
-     *
-     * @example
-     * await Nexus.identify({ id: 'usr_12345', country: 'VN' });
      */
     static identify(user: UserContext): Promise<void>;
     /**
      * Resets user context to anonymous state (e.g. on logout).
-     *
-     * @example
-     * Nexus.reset(); // called on user logout
      */
     static reset(): void;
     /**
      * Gracefully tears down both clients, closing SSE connections and flushing pending events.
-     *
-     * @example
-     * await Nexus.destroy();
      */
     static destroy(): Promise<void>;
 }
 
 /**
- * @fileoverview React Context Provider and hooks for the Nexus SDK umbrella.
+ * @fileoverview React Context Provider, hooks, and Error Boundary for the Nexus SDK.
  * @module @nexus/sdk/react
  */
 
@@ -156,12 +152,13 @@ interface NexusContextValue {
     tracker: NexusTrackerClient;
     nexus: Nexus;
 }
+declare const NexusContext: React.Context<NexusContextValue | null>;
 /**
  * Props for the NexusProvider component.
  */
 interface NexusProviderProps extends NexusInitOptions {
     /** Child components that will have access to Nexus context. */
-    children?: React.ReactNode | any;
+    children?: React.ReactNode;
 }
 /**
  * React Context Provider that initializes the Nexus SDK and makes it available
@@ -194,11 +191,6 @@ declare function NexusProvider({ children, ...initOptions }: NexusProviderProps)
  *
  * @returns Object with `flags`, `tracker`, and `nexus` properties.
  * @throws {Error} If called outside of a `NexusProvider`.
- *
- * @example
- * const { flags, tracker } = useNexus();
- * const enabled = flags.isEnabled('checkout_v2');
- * tracker.captureError(new Error('something failed'));
  */
 declare function useNexus(): NexusContextValue;
 /**
@@ -209,14 +201,6 @@ interface UseFlagResult {
     enabled: boolean;
     /**
      * Retrieves a specific variant value from this flag.
-     *
-     * @param variantKey - Property name inside the variants object.
-     * @param defaultValue - Fallback if variant is not found.
-     * @returns Typed variant value.
-     *
-     * @example
-     * const { enabled, getVariant } = useFlag('promo_banner_v2');
-     * const rate = getVariant<number>('discount_rate', 10);
      */
     getVariant: <T = unknown>(variantKey: string, defaultValue?: T) => T;
     /** Full evaluation result including reason and version. */
@@ -224,26 +208,77 @@ interface UseFlagResult {
 }
 /**
  * React hook for subscribing to a feature flag's real-time state.
+ */
+declare function useFlag(key: string, defaultEnabled?: boolean): UseFlagResult;
+interface NexusGuardProps {
+    /** Component tree to wrap with error boundary protection. */
+    children?: React.ReactNode;
+    /**
+     * Custom fallback UI to display on crash.
+     * Can be a static ReactNode or a render function receiving `NexusErrorInfo`.
+     */
+    fallback?: React.ReactNode | ((info: NexusErrorInfo) => React.ReactNode);
+    /** Callback fired immediately when an error is caught. */
+    onError?: (error: Error, info: NexusErrorInfo) => void;
+    /** Automatically resets the error boundary on browser navigation / popstate. */
+    resetOnNavigation?: boolean;
+    /** Array of values that will trigger an automatic reset when changed. */
+    resetKeys?: unknown[];
+    /** Custom tags attached to errors captured by this guard. */
+    tags?: Record<string, string>;
+    /** Optional custom tracker instance. Defaults to context or singleton. */
+    tracker?: NexusTrackerClient;
+}
+interface NexusGuardState {
+    hasError: boolean;
+    errorInfo: NexusErrorInfo | null;
+}
+/**
+ * React Error Boundary component powered by Nexus telemetry.
+ * Prevents whole-app white-screen crashes, sends crash telemetry with component stack traces,
+ * and allows customized graceful degradation.
  *
- * Automatically re-renders when the flag changes via SSE updates.
- * Returns a stable result without triggering additional re-renders if unchanged.
- *
- * @param key - Flag programmatic identifier.
- * @param defaultEnabled - Fallback boolean if flag is not yet evaluated. Defaults to false.
- * @returns {@link UseFlagResult} with `enabled`, `getVariant`, and `result`.
+ * @example
+ * // Global app guard with custom render fallback
+ * <NexusGuard fallback={({ error, errorId, reset }) => (
+ *   <div className="error-card">
+ *     <h2>Something went wrong</h2>
+ *     <p>Support Reference: {errorId}</p>
+ *     <button onClick={reset}>Try Again</button>
+ *   </div>
+ * )}>
+ *   <App />
+ * </NexusGuard>
  *
  * @example
- * function CheckoutButton() {
- *   const { enabled, getVariant } = useFlag('checkout_redesign');
- *   const theme = getVariant<string>('theme', 'default');
+ * // Isolated widget guard (e.g. sidebar or checkout card)
+ * <NexusGuard fallback={<p>Sidebar temporarily unavailable.</p>}>
+ *   <Sidebar />
+ * </NexusGuard>
+ */
+declare class NexusGuard extends React.Component<NexusGuardProps, NexusGuardState> {
+    static contextType: React.Context<NexusContextValue | null>;
+    context: React.ContextType<typeof NexusContext>;
+    constructor(props: NexusGuardProps);
+    static getDerivedStateFromError(error: Error): Partial<NexusGuardState>;
+    componentDidCatch(error: Error, reactInfo: React.ErrorInfo): void;
+    componentDidMount(): void;
+    componentDidUpdate(prevProps: NexusGuardProps): void;
+    componentWillUnmount(): void;
+    private handleNavigation;
+    /** Resets the error boundary state back to healthy rendering. */
+    reset: () => void;
+    render(): React.ReactNode;
+}
+/**
+ * Higher-Order Component (HOC) variant of NexusGuard.
+ * Wraps any component with an isolated Error Boundary.
  *
- *   return (
- *     <button className={enabled ? `btn-${theme}` : 'btn-default'}>
- *       {enabled ? 'New Checkout' : 'Checkout'}
- *     </button>
- *   );
- * }
+ * @example
+ * const SafeSidebar = withNexusGuard(Sidebar, {
+ *   fallback: <div>Sidebar error</div>,
+ * });
  */
-declare function useFlag(key: string, defaultEnabled?: boolean): UseFlagResult;
+declare function withNexusGuard<P extends object>(Component: React.ComponentType<P>, options?: Omit<NexusGuardProps, 'children'>): React.FC<P>;
 
-export { NexusProvider, type NexusProviderProps, type UseFlagResult, useFlag, useNexus };
+export { NexusContext, type NexusContextValue, NexusGuard, type NexusGuardProps, type NexusGuardState, NexusProvider, type NexusProviderProps, type UseFlagResult, useFlag, useNexus, withNexusGuard };

package/dist/react.d.ts

@@ -1,23 +1,34 @@
 import React from 'react';
-import { NexusFlagsOptions, NexusFlagsClient } from '@nexussdk/flags';
-import { NexusTrackerOptions, NexusTrackerClient } from '@nexussdk/tracker';
-import { UserContext, FlagEvaluationResult } from '@nexussdk/contracts';
+import { NexusFlagsClient, NexusFlagsOptions } from '@nexussdk/flags';
+import { NexusTrackerClient, NexusTrackerOptions } from '@nexussdk/tracker';
+import { UserContext, SamplingConfig, TransportPlugin, PerformanceVitalsOptions, SeverityLevel, Breadcrumb, NexusErrorInfo, FlagEvaluationResult } from '@nexussdk/contracts';
 
 /**
  * @fileoverview Unified Nexus singleton facade wrapping Flags and Tracker clients.
  * @module @nexus/sdk/nexus
  */
 
+/**
+ * Dev server routing configuration.
+ */
+interface NexusDevServerOptions {
+    /** Enable local dev server ingestion mode. Auto-enabled in development if true. */
+    enabled?: boolean;
+    /** Port the dev server is listening on. Defaults to 4567. */
+    port?: number;
+    /** Host the dev server is bound to. Defaults to 'localhost'. */
+    host?: string;
+}
 /**
  * Unified initialization options for the Nexus SDK umbrella.
  *
  * @example
  * Nexus.init({
  *   apiKey: 'pk_live_...',
- *   baseUrl: 'http://localhost:8080',
  *   user: { id: 'usr_12345', country: 'VN' },
  *   environment: 'production',
  *   autoCapture: true,
+ *   devServer: { enabled: process.env.NODE_ENV === 'development' },
  * });
  */
 interface NexusInitOptions {
@@ -33,6 +44,14 @@ interface NexusInitOptions {
     tags?: Record<string, string>;
     /** Toggle automated global error capture. Defaults to true. */
     autoCapture?: boolean;
+    /** Client-side rate limiting and deduplication sampling options. */
+    sampling?: SamplingConfig;
+    /** Pluggable transport adapter ('fetch', 'console', 'localStorage', custom fn). */
+    transport?: TransportPlugin;
+    /** Web Vitals performance observer options, or true for default observation. */
+    vitals?: boolean | PerformanceVitalsOptions;
+    /** Local dev server auto-routing configuration. */
+    devServer?: NexusDevServerOptions;
     /** Additional flags-specific options. */
     flags?: Partial<NexusFlagsOptions>;
     /** Additional tracker-specific options. */
@@ -59,6 +78,7 @@ interface NexusInitOptions {
  */
 declare class Nexus {
     private static instance;
+    private static vitalsCleanup;
     /** The underlying feature flags client instance. */
     readonly flags: NexusFlagsClient;
     /** The underlying error tracker client instance. */
@@ -71,9 +91,6 @@ declare class Nexus {
      *
      * @param options - SDK configuration options.
      * @returns The initialized Nexus singleton instance.
-     *
-     * @example
-     * const nexus = Nexus.init({ apiKey: 'pk_live_...' });
      */
     static init(options?: NexusInitOptions): Nexus;
     /**
@@ -81,73 +98,52 @@ declare class Nexus {
      *
      * @returns The active Nexus instance.
      * @throws {Error} If `Nexus.init()` has not been called yet.
-     *
-     * @example
-     * const nexus = Nexus.getInstance();
-     * nexus.flags.isEnabled('checkout_v2');
      */
     static getInstance(): Nexus;
     /**
      * Convenience method: Check if a feature flag is enabled.
-     *
-     * @param key - Flag identifier.
-     * @param defaultValue - Fallback if flag is missing.
-     * @returns Boolean enabled state.
-     *
-     * @example
-     * if (Nexus.isEnabled('checkout_redesign')) { ... }
      */
     static isEnabled(key: string, defaultValue?: boolean): boolean;
     /**
      * Convenience method: Get a flag variant value.
-     *
-     * @param key - Flag identifier.
-     * @param variantKey - Variant property name.
-     * @param defaultValue - Fallback value.
-     * @returns Variant value cast to type T.
-     *
-     * @example
-     * const rate = Nexus.getVariant<number>('promo_banner_v2', 'discount_rate', 10);
      */
     static getVariant<T = unknown>(key: string, variantKey: string, defaultValue?: T): T;
     /**
      * Convenience method: Capture an error manually.
-     *
-     * @param error - Error instance, string, or unknown value.
-     * @param extra - Optional metadata tags.
-     *
-     * @example
-     * Nexus.captureError(new TypeError('Cannot read properties of null'));
      */
     static captureError(error: unknown, extra?: Record<string, unknown>): void;
+    /**
+     * Convenience method: Capture an informational or warning message event.
+     */
+    static captureMessage(message: string, level?: SeverityLevel, extra?: Record<string, unknown>): void;
+    /**
+     * Convenience method: Add a breadcrumb manually.
+     */
+    static addBreadcrumb(breadcrumb: Breadcrumb): void;
+    /**
+     * Convenience method: Set extra contextual metadata.
+     */
+    static setExtra(key: string, value: unknown): void;
+    /**
+     * Convenience method: Attach Web Vitals observer to tracker.
+     */
+    static attachWebVitals(options?: PerformanceVitalsOptions): () => void;
     /**
      * Convenience method: Update user context for both flags and tracker.
-     *
-     * @param user - New user context (merged with existing).
-     * @returns Promise resolving after flags refresh.
-     *
-     * @example
-     * await Nexus.identify({ id: 'usr_12345', country: 'VN' });
      */
     static identify(user: UserContext): Promise<void>;
     /**
      * Resets user context to anonymous state (e.g. on logout).
-     *
-     * @example
-     * Nexus.reset(); // called on user logout
      */
     static reset(): void;
     /**
      * Gracefully tears down both clients, closing SSE connections and flushing pending events.
-     *
-     * @example
-     * await Nexus.destroy();
      */
     static destroy(): Promise<void>;
 }
 
 /**
- * @fileoverview React Context Provider and hooks for the Nexus SDK umbrella.
+ * @fileoverview React Context Provider, hooks, and Error Boundary for the Nexus SDK.
  * @module @nexus/sdk/react
  */
 
@@ -156,12 +152,13 @@ interface NexusContextValue {
     tracker: NexusTrackerClient;
     nexus: Nexus;
 }
+declare const NexusContext: React.Context<NexusContextValue | null>;
 /**
  * Props for the NexusProvider component.
  */
 interface NexusProviderProps extends NexusInitOptions {
     /** Child components that will have access to Nexus context. */
-    children?: React.ReactNode | any;
+    children?: React.ReactNode;
 }
 /**
  * React Context Provider that initializes the Nexus SDK and makes it available
@@ -194,11 +191,6 @@ declare function NexusProvider({ children, ...initOptions }: NexusProviderProps)
  *
  * @returns Object with `flags`, `tracker`, and `nexus` properties.
  * @throws {Error} If called outside of a `NexusProvider`.
- *
- * @example
- * const { flags, tracker } = useNexus();
- * const enabled = flags.isEnabled('checkout_v2');
- * tracker.captureError(new Error('something failed'));
  */
 declare function useNexus(): NexusContextValue;
 /**
@@ -209,14 +201,6 @@ interface UseFlagResult {
     enabled: boolean;
     /**
      * Retrieves a specific variant value from this flag.
-     *
-     * @param variantKey - Property name inside the variants object.
-     * @param defaultValue - Fallback if variant is not found.
-     * @returns Typed variant value.
-     *
-     * @example
-     * const { enabled, getVariant } = useFlag('promo_banner_v2');
-     * const rate = getVariant<number>('discount_rate', 10);
      */
     getVariant: <T = unknown>(variantKey: string, defaultValue?: T) => T;
     /** Full evaluation result including reason and version. */
@@ -224,26 +208,77 @@ interface UseFlagResult {
 }
 /**
  * React hook for subscribing to a feature flag's real-time state.
+ */
+declare function useFlag(key: string, defaultEnabled?: boolean): UseFlagResult;
+interface NexusGuardProps {
+    /** Component tree to wrap with error boundary protection. */
+    children?: React.ReactNode;
+    /**
+     * Custom fallback UI to display on crash.
+     * Can be a static ReactNode or a render function receiving `NexusErrorInfo`.
+     */
+    fallback?: React.ReactNode | ((info: NexusErrorInfo) => React.ReactNode);
+    /** Callback fired immediately when an error is caught. */
+    onError?: (error: Error, info: NexusErrorInfo) => void;
+    /** Automatically resets the error boundary on browser navigation / popstate. */
+    resetOnNavigation?: boolean;
+    /** Array of values that will trigger an automatic reset when changed. */
+    resetKeys?: unknown[];
+    /** Custom tags attached to errors captured by this guard. */
+    tags?: Record<string, string>;
+    /** Optional custom tracker instance. Defaults to context or singleton. */
+    tracker?: NexusTrackerClient;
+}
+interface NexusGuardState {
+    hasError: boolean;
+    errorInfo: NexusErrorInfo | null;
+}
+/**
+ * React Error Boundary component powered by Nexus telemetry.
+ * Prevents whole-app white-screen crashes, sends crash telemetry with component stack traces,
+ * and allows customized graceful degradation.
  *
- * Automatically re-renders when the flag changes via SSE updates.
- * Returns a stable result without triggering additional re-renders if unchanged.
- *
- * @param key - Flag programmatic identifier.
- * @param defaultEnabled - Fallback boolean if flag is not yet evaluated. Defaults to false.
- * @returns {@link UseFlagResult} with `enabled`, `getVariant`, and `result`.
+ * @example
+ * // Global app guard with custom render fallback
+ * <NexusGuard fallback={({ error, errorId, reset }) => (
+ *   <div className="error-card">
+ *     <h2>Something went wrong</h2>
+ *     <p>Support Reference: {errorId}</p>
+ *     <button onClick={reset}>Try Again</button>
+ *   </div>
+ * )}>
+ *   <App />
+ * </NexusGuard>
  *
  * @example
- * function CheckoutButton() {
- *   const { enabled, getVariant } = useFlag('checkout_redesign');
- *   const theme = getVariant<string>('theme', 'default');
+ * // Isolated widget guard (e.g. sidebar or checkout card)
+ * <NexusGuard fallback={<p>Sidebar temporarily unavailable.</p>}>
+ *   <Sidebar />
+ * </NexusGuard>
+ */
+declare class NexusGuard extends React.Component<NexusGuardProps, NexusGuardState> {
+    static contextType: React.Context<NexusContextValue | null>;
+    context: React.ContextType<typeof NexusContext>;
+    constructor(props: NexusGuardProps);
+    static getDerivedStateFromError(error: Error): Partial<NexusGuardState>;
+    componentDidCatch(error: Error, reactInfo: React.ErrorInfo): void;
+    componentDidMount(): void;
+    componentDidUpdate(prevProps: NexusGuardProps): void;
+    componentWillUnmount(): void;
+    private handleNavigation;
+    /** Resets the error boundary state back to healthy rendering. */
+    reset: () => void;
+    render(): React.ReactNode;
+}
+/**
+ * Higher-Order Component (HOC) variant of NexusGuard.
+ * Wraps any component with an isolated Error Boundary.
  *
- *   return (
- *     <button className={enabled ? `btn-${theme}` : 'btn-default'}>
- *       {enabled ? 'New Checkout' : 'Checkout'}
- *     </button>
- *   );
- * }
+ * @example
+ * const SafeSidebar = withNexusGuard(Sidebar, {
+ *   fallback: <div>Sidebar error</div>,
+ * });
  */
-declare function useFlag(key: string, defaultEnabled?: boolean): UseFlagResult;
+declare function withNexusGuard<P extends object>(Component: React.ComponentType<P>, options?: Omit<NexusGuardProps, 'children'>): React.FC<P>;
 
-export { NexusProvider, type NexusProviderProps, type UseFlagResult, useFlag, useNexus };
+export { NexusContext, type NexusContextValue, NexusGuard, type NexusGuardProps, type NexusGuardState, NexusProvider, type NexusProviderProps, type UseFlagResult, useFlag, useNexus, withNexusGuard };

package/dist/react.mjs

@@ -1 +1,2 @@
-import N,{createContext,useRef,useMemo,useEffect,useContext,useState}from'react';import {NexusFlagsClient}from'@nexussdk/flags';import {NexusTrackerClient}from'@nexussdk/tracker';var a=class e{static instance=null;flags;tracker;constructor(n={}){let{apiKey:t,baseUrl:s,user:i,environment:r,tags:u,autoCapture:o,flags:p,tracker:g}=n;this.flags=new NexusFlagsClient({apiKey:t,baseUrl:s,user:i,...p}),this.tracker=new NexusTrackerClient({apiKey:t,baseUrl:s,environment:r,tags:u,autoCapture:o,...g});}static init(n={}){return e.instance||(e.instance=new e(n)),e.instance}static getInstance(){if(!e.instance)throw new Error('[Nexus SDK] Not initialized. Call Nexus.init({ apiKey: "..." }) first.');return e.instance}static isEnabled(n,t=false){return e.getInstance().flags.isEnabled(n,t)}static getVariant(n,t,s){return e.getInstance().flags.getVariant(n,t,s)}static captureError(n,t){e.getInstance().tracker.captureError(n,t);}static async identify(n){let t=e.getInstance();t.tracker.setUser(n),await t.flags.identify(n);}static reset(){let n=e.getInstance();n.tracker.setUser(null),n.flags.reset();}static async destroy(){e.instance&&(await e.instance.tracker.flush(),e.instance.tracker.destroy(),e.instance.flags.destroy(),e.instance=null);}};var x=createContext(null);function y({children:e,...n}){let t=useRef(null);t.current||(t.current=a.init(n));let s=useMemo(()=>({flags:t.current.flags,tracker:t.current.tracker,nexus:t.current}),[]);return useEffect(()=>()=>{a.destroy();},[]),N.createElement(x.Provider,{value:s},e)}function C(){let e=useContext(x);if(!e)throw new Error("[Nexus SDK] useNexus() must be called inside a <NexusProvider>.");return e}function I(e,n=false){let{flags:t}=C(),[s,i]=useState(()=>t.isEnabled(e)!==n?{key:e,enabled:t.isEnabled(e),variants:{},reason:"DEFAULT_ENABLED",version:0}:null);return useEffect(()=>{let r=t.isEnabled(e,n);return r!==(s?.enabled??n)&&i({key:e,enabled:r,variants:{},reason:"DEFAULT_ENABLED",version:0}),t.onFlagChange(e,o=>{i(o);})},[e]),useMemo(()=>({enabled:s?.enabled??t.isEnabled(e,n),getVariant:(r,u)=>t.getVariant(e,r,u),result:s}),[s,e,t,n])}export{y as NexusProvider,I as useFlag,C as useNexus};
+import i,{createContext,useRef,useMemo,useEffect,useContext,useState}from'react';import {NexusFlagsClient}from'@nexussdk/flags';import {parseStackTrace,computeFingerprint,NexusTrackerClient,attachWebVitals}from'@nexussdk/tracker';var l=class t{static instance=null;static vitalsCleanup=null;flags;tracker;constructor(e={}){let{apiKey:r,baseUrl:n,user:s,environment:a,tags:o,autoCapture:u,sampling:m,transport:d,vitals:c,devServer:p,flags:y,tracker:C}=e;this.flags=new NexusFlagsClient({apiKey:r,baseUrl:n,user:s,...y});let N=n,R=d;if(p?.enabled){let f=p.port??4567;N=`http://${p.host??"localhost"}:${f}`;}if(this.tracker=new NexusTrackerClient({apiKey:r,baseUrl:N,environment:a,tags:o,autoCapture:u,sampling:m,transport:R,...C}),c){let f=typeof c=="object"?c:{};t.vitalsCleanup=attachWebVitals(this.tracker,f);}}static init(e={}){return t.instance||(t.instance=new t(e)),t.instance}static getInstance(){if(!t.instance)throw new Error('[Nexus SDK] Not initialized. Call Nexus.init({ apiKey: "..." }) first.');return t.instance}static isEnabled(e,r=false){return t.getInstance().flags.isEnabled(e,r)}static getVariant(e,r,n){return t.getInstance().flags.getVariant(e,r,n)}static captureError(e,r){t.getInstance().tracker.captureError(e,r);}static captureMessage(e,r="info",n){t.getInstance().tracker.captureMessage(e,r,n);}static addBreadcrumb(e){t.getInstance().tracker.addBreadcrumb(e);}static setExtra(e,r){t.getInstance().tracker.setExtra(e,r);}static attachWebVitals(e){return attachWebVitals(t.getInstance().tracker,e)}static async identify(e){let r=t.getInstance();r.tracker.setUser(e),await r.flags.identify(e);}static reset(){let e=t.getInstance();e.tracker.setUser(null),e.flags.reset();}static async destroy(){t.vitalsCleanup&&(t.vitalsCleanup(),t.vitalsCleanup=null),t.instance&&(await t.instance.tracker.flush(),t.instance.tracker.destroy(),t.instance.flags.destroy(),t.instance=null);}};var g=createContext(null);function M({children:t,...e}){let r=useRef(null);r.current||(r.current=l.init(e));let n=useMemo(()=>({flags:r.current.flags,tracker:r.current.tracker,nexus:r.current}),[]);return useEffect(()=>()=>{l.destroy();},[]),i.createElement(g.Provider,{value:n},t)}function O(){let t=useContext(g);if(!t)throw new Error("[Nexus SDK] useNexus() must be called inside a <NexusProvider>.");return t}function W(t,e=false){let{flags:r}=O(),[n,s]=useState(()=>r.isEnabled(t)!==e?{key:t,enabled:r.isEnabled(t),variants:{},reason:"DEFAULT_ENABLED",version:0}:null);return useEffect(()=>{let a=r.isEnabled(t,e);return a!==(n?.enabled??e)&&s({key:t,enabled:a,variants:{},reason:"DEFAULT_ENABLED",version:0}),r.onFlagChange(t,u=>{s(u);})},[t]),useMemo(()=>({enabled:n?.enabled??r.isEnabled(t,e),getVariant:(a,o)=>r.getVariant(t,a,o),result:n}),[n,t,r,e])}var x=class extends i.Component{static contextType=g;constructor(e){super(e),this.state={hasError:false,errorInfo:null};}static getDerivedStateFromError(e){let r=parseStackTrace(e.stack),s=`NX-${computeFingerprint(e.name,e.message,r[0]).replace(/^fp_/,"").slice(0,8).toUpperCase()}`;return {hasError:true,errorInfo:{error:e,errorId:s,reset:()=>{}}}}componentDidCatch(e,r){let{onError:n,tags:s,tracker:a}=this.props,o=a;if(!o&&this.context?.tracker&&(o=this.context.tracker),!o)try{o=l.getInstance().tracker;}catch{}let u=parseStackTrace(e.stack),d=`NX-${computeFingerprint(e.name,e.message,u[0]).replace(/^fp_/,"").slice(0,8).toUpperCase()}`,c={error:e,errorId:d,componentStack:r.componentStack??void 0,reset:()=>this.reset()};if(this.setState({errorInfo:c}),o&&o.captureError(e,{tags:{...s,guardErrorId:d},componentStack:r.componentStack??void 0}),n)try{n(e,c);}catch(p){typeof console<"u"&&console.warn("[NexusGuard] onError handler threw:",p);}}componentDidMount(){this.props.resetOnNavigation&&typeof window<"u"&&window.addEventListener("popstate",this.handleNavigation);}componentDidUpdate(e){let{resetKeys:r}=this.props;this.state.hasError&&r&&e.resetKeys&&r.some((s,a)=>s!==e.resetKeys[a])&&this.reset();}componentWillUnmount(){this.props.resetOnNavigation&&typeof window<"u"&&window.removeEventListener("popstate",this.handleNavigation);}handleNavigation=()=>{this.state.hasError&&this.reset();};reset=()=>{this.setState({hasError:false,errorInfo:null});};render(){let{hasError:e,errorInfo:r}=this.state,{fallback:n,children:s}=this.props;return e&&r?typeof n=="function"?n(r):n||i.createElement("div",{role:"alert",style:{padding:"16px 20px",margin:"12px 0",borderRadius:"8px",backgroundColor:"#1f1315",border:"1px solid #7f1d1d",color:"#fca5a5",fontFamily:"-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",fontSize:"14px",lineHeight:1.5}},i.createElement("div",{style:{display:"flex",alignItems:"center",justifyContent:"space-between",marginBottom:"8px"}},i.createElement("strong",{style:{color:"#ef4444"}},"Application Error Encountered"),i.createElement("span",{style:{fontSize:"12px",fontFamily:"monospace",background:"#450a0a",padding:"2px 8px",borderRadius:"4px"}},r.errorId)),i.createElement("p",{style:{margin:"0 0 12px 0",color:"#fecaca"}},r.error.message),i.createElement("button",{type:"button",onClick:()=>this.reset(),style:{background:"#b91c1c",border:"none",color:"#fff",padding:"6px 14px",borderRadius:"6px",fontSize:"13px",cursor:"pointer",fontWeight:500}},"Retry")):s}};function $(t,e={}){let r=s=>i.createElement(x,e,i.createElement(t,s)),n=t.displayName||t.name||"Component";return r.displayName=`withNexusGuard(${n})`,r}
+export{g as NexusContext,x as NexusGuard,M as NexusProvider,W as useFlag,O as useNexus,$ as withNexusGuard};

package/dist/vue.cjs

@@ -0,0 +1,2 @@
+'use strict';var vue=require('vue'),flags=require('@nexussdk/flags'),tracker=require('@nexussdk/tracker');var p=class e{static instance=null;static vitalsCleanup=null;flags;tracker;constructor(t={}){let{apiKey:n,baseUrl:r,user:o,environment:a,tags:s,autoCapture:i,sampling:f,transport:x,vitals:l,devServer:c,flags:g,tracker:C}=t;this.flags=new flags.NexusFlagsClient({apiKey:n,baseUrl:r,user:o,...g});let m=r,I=x;if(c?.enabled){let d=c.port??4567;m=`http://${c.host??"localhost"}:${d}`;}if(this.tracker=new tracker.NexusTrackerClient({apiKey:n,baseUrl:m,environment:a,tags:s,autoCapture:i,sampling:f,transport:I,...C}),l){let d=typeof l=="object"?l:{};e.vitalsCleanup=tracker.attachWebVitals(this.tracker,d);}}static init(t={}){return e.instance||(e.instance=new e(t)),e.instance}static getInstance(){if(!e.instance)throw new Error('[Nexus SDK] Not initialized. Call Nexus.init({ apiKey: "..." }) first.');return e.instance}static isEnabled(t,n=false){return e.getInstance().flags.isEnabled(t,n)}static getVariant(t,n,r){return e.getInstance().flags.getVariant(t,n,r)}static captureError(t,n){e.getInstance().tracker.captureError(t,n);}static captureMessage(t,n="info",r){e.getInstance().tracker.captureMessage(t,n,r);}static addBreadcrumb(t){e.getInstance().tracker.addBreadcrumb(t);}static setExtra(t,n){e.getInstance().tracker.setExtra(t,n);}static attachWebVitals(t){return tracker.attachWebVitals(e.getInstance().tracker,t)}static async identify(t){let n=e.getInstance();n.tracker.setUser(t),await n.flags.identify(t);}static reset(){let t=e.getInstance();t.tracker.setUser(null),t.flags.reset();}static async destroy(){e.vitalsCleanup&&(e.vitalsCleanup(),e.vitalsCleanup=null),e.instance&&(await e.instance.tracker.flush(),e.instance.tracker.destroy(),e.instance.flags.destroy(),e.instance=null);}};var y=Symbol("NexusSDK"),H={install(e,t={}){let n=p.init(t),r={flags:n.flags,tracker:n.tracker,nexus:n};e.provide(y,r);let o=e.config.errorHandler;e.config.errorHandler=(a,s,i)=>{n.tracker.captureError(a,{componentStack:i,tags:{framework:"vue3",component:s?.$options?.name||"AnonymousComponent"}}),o&&o(a,s,i);},e.component("NexusGuard",R);}};function N(){let e=vue.inject(y);if(e)return e;let t=p.getInstance();return {flags:t.flags,tracker:t.tracker,nexus:t}}function A(e,t=false){let{flags:n}=N(),r=vue.ref(n.isEnabled(e,t)),o=vue.shallowRef(null),a=n.onFlagChange(e,s=>{r.value=s.enabled,o.value=s;});return vue.onUnmounted(()=>{a();}),{enabled:r,getVariant:(s,i)=>n.getVariant(e,s,i),result:o}}var R=vue.defineComponent({name:"NexusGuard",props:{onError:{type:Function,default:void 0},tags:{type:Object,default:()=>({})}},setup(e,{slots:t}){let n=vue.ref(false),r=vue.shallowRef(null),o=()=>{n.value=false,r.value=null;};return vue.onErrorCaptured((a,s,i)=>{let f=tracker.parseStackTrace(a.stack),l=`NX-${tracker.computeFingerprint(a.name,a.message,f[0]).replace(/^fp_/,"").slice(0,8).toUpperCase()}`,c={error:a,errorId:l,componentStack:i,reset:o};n.value=true,r.value=c;try{let{tracker:g}=N();g.captureError(a,{componentStack:i,tags:{...e.tags,guardErrorId:l,framework:"vue3",component:s?.$options?.name||"AnonymousComponent"}});}catch{}if(e.onError)try{e.onError(a,c);}catch{}return  false}),()=>n.value&&r.value?t.fallback?t.fallback(r.value):vue.h("div",{role:"alert",style:{padding:"16px 20px",margin:"12px 0",borderRadius:"8px",backgroundColor:"#1f1315",border:"1px solid #7f1d1d",color:"#fca5a5",fontFamily:"-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",fontSize:"14px"}},[vue.h("div",{style:{display:"flex",justifyContent:"space-between",marginBottom:"8px"}},[vue.h("strong",{style:{color:"#ef4444"}},"Vue Component Crash Protected"),vue.h("span",{style:{fontFamily:"monospace",fontSize:"12px",background:"#450a0a",padding:"2px 8px",borderRadius:"4px"}},r.value.errorId)]),vue.h("p",{style:{margin:"0 0 12px 0",color:"#fecaca"}},r.value.error.message),vue.h("button",{type:"button",onClick:o,style:{background:"#b91c1c",border:"none",color:"#fff",padding:"6px 14px",borderRadius:"6px",fontSize:"13px",cursor:"pointer",fontWeight:"500"}},"Retry Component")]):t.default?t.default():null}});
+exports.NEXUS_KEY=y;exports.NexusGuardVue=R;exports.NexusPlugin=H;exports.useFlag=A;exports.useNexus=N;