@nexussdk/contracts 0.0.3 → 0.0.4

package/dist/index.d.mts

@@ -1,4 +1,4 @@
 export { Account, AccountStatus, ApiKey, ApiKeyType, Environment, GeneratedApiKeyResponse, LoginDto, PlanTier, Project, RegisterAccountDto, SessionPayload } from './auth.mjs';
 export { BatchFlagEvaluation, CreateFlagDto, FeatureFlag, FlagEvaluationResult, FlagStreamEvent, FlagVariants, RuleOperator, TargetingRule, UpdateFlagDto, UserContext, VariantValue } from './flags.mjs';
-export { Breadcrumb, BreadcrumbCategory, DeviceContext, ErrorEventEntity, ErrorEventPayload, ErrorGroupSummary, SeverityLevel, StackFrame } from './tracker.mjs';
+export { Breadcrumb, BreadcrumbCategory, DevServerEventEnvelope, DeviceContext, ErrorEventEntity, ErrorEventPayload, ErrorGroupSummary, NexusErrorInfo, PerformanceVitalEntry, PerformanceVitalsOptions, SamplingConfig, SeverityLevel, StackFrame, TransportPlugin, VitalMetricName } from './tracker.mjs';
 export { NEXUS_ERROR_BASE, ProblemDetails } from './rfc7807.mjs';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { Account, AccountStatus, ApiKey, ApiKeyType, Environment, GeneratedApiKeyResponse, LoginDto, PlanTier, Project, RegisterAccountDto, SessionPayload } from './auth.js';
 export { BatchFlagEvaluation, CreateFlagDto, FeatureFlag, FlagEvaluationResult, FlagStreamEvent, FlagVariants, RuleOperator, TargetingRule, UpdateFlagDto, UserContext, VariantValue } from './flags.js';
-export { Breadcrumb, BreadcrumbCategory, DeviceContext, ErrorEventEntity, ErrorEventPayload, ErrorGroupSummary, SeverityLevel, StackFrame } from './tracker.js';
+export { Breadcrumb, BreadcrumbCategory, DevServerEventEnvelope, DeviceContext, ErrorEventEntity, ErrorEventPayload, ErrorGroupSummary, NexusErrorInfo, PerformanceVitalEntry, PerformanceVitalsOptions, SamplingConfig, SeverityLevel, StackFrame, TransportPlugin, VitalMetricName } from './tracker.js';
 export { NEXUS_ERROR_BASE, ProblemDetails } from './rfc7807.js';

package/dist/tracker.d.mts

@@ -194,4 +194,147 @@ interface ErrorGroupSummary {
     lastSeenAt: string;
 }
 
-export { type Breadcrumb, type BreadcrumbCategory, type DeviceContext, type ErrorEventEntity, type ErrorEventPayload, type ErrorGroupSummary, type SeverityLevel, type StackFrame, UserContext };
+/**
+ * Normalized error information passed to NexusGuard fallback render function.
+ * Framework-agnostic — used by React, Vue, and Vanilla integrations.
+ *
+ * @example
+ * // React render prop
+ * <NexusGuard fallback={({ error, errorId, reset }) => (
+ *   <div>Error #{errorId}: {error.message} <button onClick={reset}>Retry</button></div>
+ * )}>
+ *   <App />
+ * </NexusGuard>
+ */
+interface NexusErrorInfo {
+    /** The original Error object that triggered the boundary. */
+    error: Error;
+    /**
+     * Deterministic fingerprint ID for this error class.
+     * Can be shown to users as a support reference code.
+     */
+    errorId: string;
+    /** Resets the error boundary back to normal rendering state. */
+    reset: () => void;
+    /** Component stack trace (React/Vue only — undefined in Vanilla). */
+    componentStack?: string;
+}
+/**
+ * Custom transport plugin for SDK error event delivery.
+ * Allows complete replacement of the default fetch-based ingestion transport.
+ *
+ * @example
+ * // Custom Sentry forwarding transport
+ * const sentryTransport: TransportPlugin = async (event) => {
+ *   Sentry.captureException(new Error(event.errorMessage));
+ * };
+ *
+ * Nexus.init({ transport: sentryTransport });
+ */
+type TransportPlugin = 'fetch' | 'console' | 'localStorage' | ((event: ErrorEventPayload) => void | Promise<void>);
+/**
+ * Client-side event sampling and rate limiting configuration.
+ *
+ * @example
+ * Nexus.init({
+ *   sampling: {
+ *     rate: 0.5,           // Capture 50% of errors
+ *     dedupeWindow: 5000,  // 5s dedup window
+ *     maxPerSession: 25,   // Max 25 unique errors per session
+ *   }
+ * });
+ */
+interface SamplingConfig {
+    /**
+     * Fraction of errors to capture and transmit. Range: 0.0 (none) to 1.0 (all).
+     * @default 1.0
+     */
+    rate?: number;
+    /**
+     * Milliseconds sliding window for client-side deduplication.
+     * Duplicate errors within this window are counted but not retransmitted.
+     * @default 10000
+     */
+    dedupeWindow?: number;
+    /**
+     * Maximum number of unique error fingerprints captured per browser session.
+     * Prevents event storms in crash-loop scenarios.
+     * @default 100
+     */
+    maxPerSession?: number;
+}
+/**
+ * Web Vitals metric names measured by the Performance observer.
+ */
+type VitalMetricName = 'LCP' | 'CLS' | 'FID' | 'TTFB' | 'INP' | 'FCP';
+/**
+ * Captured Web Vitals performance metric entry.
+ *
+ * @example
+ * const entry: PerformanceVitalEntry = {
+ *   name: 'LCP',
+ *   value: 1200,
+ *   rating: 'good',
+ *   delta: 1200,
+ *   navigationType: 'navigate',
+ * };
+ */
+interface PerformanceVitalEntry {
+    /** Metric name. */
+    name: VitalMetricName;
+    /** Metric value in milliseconds (or unitless score for CLS). */
+    value: number;
+    /** Quality rating based on Core Web Vitals thresholds. */
+    rating: 'good' | 'needs-improvement' | 'poor';
+    /** Delta from previous measurement in the same session. */
+    delta: number;
+    /** Navigation type that initiated the metric measurement. */
+    navigationType: 'navigate' | 'reload' | 'back-forward' | 'prerender' | string;
+}
+/**
+ * Configuration for the Web Vitals performance observer.
+ *
+ * @example
+ * attachWebVitals(tracker, {
+ *   captureAsEvents: true,
+ *   poorRatingOnly: true,
+ * });
+ */
+interface PerformanceVitalsOptions {
+    /**
+     * When true, captures poor/needs-improvement vitals as full error events.
+     * When false, captures all vitals as breadcrumbs only.
+     * @default false
+     */
+    captureAsEvents?: boolean;
+    /**
+     * When true, only captures metrics rated 'poor' or 'needs-improvement'.
+     * @default false
+     */
+    poorRatingOnly?: boolean;
+    /**
+     * Subset of vital names to observe. Defaults to all supported vitals.
+     * @default ['LCP', 'CLS', 'FID', 'TTFB', 'INP', 'FCP']
+     */
+    vitals?: VitalMetricName[];
+    /**
+     * Long task duration threshold in milliseconds. Tasks exceeding this
+     * are recorded as breadcrumbs with category 'performance'.
+     * @default 50
+     */
+    longTaskThresholdMs?: number;
+}
+/**
+ * Event envelope used by the nexus-dev local ingestion server.
+ * Wraps ErrorEventPayload with server-assigned metadata.
+ */
+interface DevServerEventEnvelope {
+    /** Monotonically increasing server-assigned event ID. */
+    id: number;
+    /** ISO timestamp when the dev server received the event. */
+    receivedAt: string;
+    /** The captured error event payload. */
+    payload: ErrorEventPayload;
+}
+
+export { type Breadcrumb, type BreadcrumbCategory, type DevServerEventEnvelope, type DeviceContext, type ErrorEventEntity, type ErrorEventPayload, type ErrorGroupSummary, type NexusErrorInfo, type PerformanceVitalEntry, type PerformanceVitalsOptions, type SamplingConfig, type SeverityLevel, type StackFrame, type TransportPlugin, UserContext, type VitalMetricName };

package/dist/tracker.d.ts

@@ -194,4 +194,147 @@ interface ErrorGroupSummary {
     lastSeenAt: string;
 }
 
-export { type Breadcrumb, type BreadcrumbCategory, type DeviceContext, type ErrorEventEntity, type ErrorEventPayload, type ErrorGroupSummary, type SeverityLevel, type StackFrame, UserContext };
+/**
+ * Normalized error information passed to NexusGuard fallback render function.
+ * Framework-agnostic — used by React, Vue, and Vanilla integrations.
+ *
+ * @example
+ * // React render prop
+ * <NexusGuard fallback={({ error, errorId, reset }) => (
+ *   <div>Error #{errorId}: {error.message} <button onClick={reset}>Retry</button></div>
+ * )}>
+ *   <App />
+ * </NexusGuard>
+ */
+interface NexusErrorInfo {
+    /** The original Error object that triggered the boundary. */
+    error: Error;
+    /**
+     * Deterministic fingerprint ID for this error class.
+     * Can be shown to users as a support reference code.
+     */
+    errorId: string;
+    /** Resets the error boundary back to normal rendering state. */
+    reset: () => void;
+    /** Component stack trace (React/Vue only — undefined in Vanilla). */
+    componentStack?: string;
+}
+/**
+ * Custom transport plugin for SDK error event delivery.
+ * Allows complete replacement of the default fetch-based ingestion transport.
+ *
+ * @example
+ * // Custom Sentry forwarding transport
+ * const sentryTransport: TransportPlugin = async (event) => {
+ *   Sentry.captureException(new Error(event.errorMessage));
+ * };
+ *
+ * Nexus.init({ transport: sentryTransport });
+ */
+type TransportPlugin = 'fetch' | 'console' | 'localStorage' | ((event: ErrorEventPayload) => void | Promise<void>);
+/**
+ * Client-side event sampling and rate limiting configuration.
+ *
+ * @example
+ * Nexus.init({
+ *   sampling: {
+ *     rate: 0.5,           // Capture 50% of errors
+ *     dedupeWindow: 5000,  // 5s dedup window
+ *     maxPerSession: 25,   // Max 25 unique errors per session
+ *   }
+ * });
+ */
+interface SamplingConfig {
+    /**
+     * Fraction of errors to capture and transmit. Range: 0.0 (none) to 1.0 (all).
+     * @default 1.0
+     */
+    rate?: number;
+    /**
+     * Milliseconds sliding window for client-side deduplication.
+     * Duplicate errors within this window are counted but not retransmitted.
+     * @default 10000
+     */
+    dedupeWindow?: number;
+    /**
+     * Maximum number of unique error fingerprints captured per browser session.
+     * Prevents event storms in crash-loop scenarios.
+     * @default 100
+     */
+    maxPerSession?: number;
+}
+/**
+ * Web Vitals metric names measured by the Performance observer.
+ */
+type VitalMetricName = 'LCP' | 'CLS' | 'FID' | 'TTFB' | 'INP' | 'FCP';
+/**
+ * Captured Web Vitals performance metric entry.
+ *
+ * @example
+ * const entry: PerformanceVitalEntry = {
+ *   name: 'LCP',
+ *   value: 1200,
+ *   rating: 'good',
+ *   delta: 1200,
+ *   navigationType: 'navigate',
+ * };
+ */
+interface PerformanceVitalEntry {
+    /** Metric name. */
+    name: VitalMetricName;
+    /** Metric value in milliseconds (or unitless score for CLS). */
+    value: number;
+    /** Quality rating based on Core Web Vitals thresholds. */
+    rating: 'good' | 'needs-improvement' | 'poor';
+    /** Delta from previous measurement in the same session. */
+    delta: number;
+    /** Navigation type that initiated the metric measurement. */
+    navigationType: 'navigate' | 'reload' | 'back-forward' | 'prerender' | string;
+}
+/**
+ * Configuration for the Web Vitals performance observer.
+ *
+ * @example
+ * attachWebVitals(tracker, {
+ *   captureAsEvents: true,
+ *   poorRatingOnly: true,
+ * });
+ */
+interface PerformanceVitalsOptions {
+    /**
+     * When true, captures poor/needs-improvement vitals as full error events.
+     * When false, captures all vitals as breadcrumbs only.
+     * @default false
+     */
+    captureAsEvents?: boolean;
+    /**
+     * When true, only captures metrics rated 'poor' or 'needs-improvement'.
+     * @default false
+     */
+    poorRatingOnly?: boolean;
+    /**
+     * Subset of vital names to observe. Defaults to all supported vitals.
+     * @default ['LCP', 'CLS', 'FID', 'TTFB', 'INP', 'FCP']
+     */
+    vitals?: VitalMetricName[];
+    /**
+     * Long task duration threshold in milliseconds. Tasks exceeding this
+     * are recorded as breadcrumbs with category 'performance'.
+     * @default 50
+     */
+    longTaskThresholdMs?: number;
+}
+/**
+ * Event envelope used by the nexus-dev local ingestion server.
+ * Wraps ErrorEventPayload with server-assigned metadata.
+ */
+interface DevServerEventEnvelope {
+    /** Monotonically increasing server-assigned event ID. */
+    id: number;
+    /** ISO timestamp when the dev server received the event. */
+    receivedAt: string;
+    /** The captured error event payload. */
+    payload: ErrorEventPayload;
+}
+
+export { type Breadcrumb, type BreadcrumbCategory, type DevServerEventEnvelope, type DeviceContext, type ErrorEventEntity, type ErrorEventPayload, type ErrorGroupSummary, type NexusErrorInfo, type PerformanceVitalEntry, type PerformanceVitalsOptions, type SamplingConfig, type SeverityLevel, type StackFrame, type TransportPlugin, UserContext, type VitalMetricName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexussdk/contracts",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "private": false,
   "publishConfig": {
     "access": "public"