@nexussdk/contracts 0.0.1

package/src/tracker.ts

@@ -0,0 +1,205 @@
+/**
+ * @fileoverview Telemetry, Breadcrumb Tracing, and Error Ingestion contracts.
+ * @module @nexus/contracts/tracker
+ */
+
+import type { Environment } from './auth.js';
+import type { UserContext } from './flags.js';
+
+/**
+ * Severity level of captured telemetry events.
+ *
+ * @example
+ * const level: SeverityLevel = 'error';
+ */
+export type SeverityLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+
+/**
+ * Categorization of user action trails leading to a crash.
+ *
+ * @example
+ * const category: BreadcrumbCategory = 'ui.click';
+ */
+export type BreadcrumbCategory = 'ui.click' | 'navigation' | 'http' | 'console' | 'custom';
+
+/**
+ * Recorded trail of user activity captured before an exception.
+ *
+ * @example
+ * const breadcrumb: Breadcrumb = {
+ *   timestamp: 1704067200000,
+ *   category: 'ui.click',
+ *   message: 'Clicked button #checkout-btn',
+ *   level: 'info',
+ *   data: { elementId: 'checkout-btn', page: '/checkout' },
+ * };
+ */
+export interface Breadcrumb {
+  /** Milliseconds epoch timestamp when event occurred. */
+  timestamp: number;
+  /** Categorical discriminator. */
+  category: BreadcrumbCategory;
+  /** Human-readable event description (e.g. "Clicked button #checkout-btn"). */
+  message: string;
+  /** Severity level of the action. */
+  level?: SeverityLevel;
+  /** Sanitized event payload (e.g. HTTP status, target route). */
+  data?: Record<string, unknown>;
+}
+
+/**
+ * Parsed and structured stack frame information.
+ *
+ * @example
+ * const frame: StackFrame = {
+ *   functionName: 'processPayment',
+ *   fileName: 'https://app.example.com/chunk.abc123.js',
+ *   lineNumber: 1,
+ *   columnNumber: 45231,
+ * };
+ */
+export interface StackFrame {
+  /** Name of the executing function or scope. */
+  functionName: string;
+  /** URL or relative path of the script file. */
+  fileName: string;
+  /** 1-based source line number. */
+  lineNumber: number;
+  /** 1-based source column number. */
+  columnNumber: number;
+  /** Extracted source context lines if available (after source map resolution). */
+  contextLines?: string[];
+}
+
+/**
+ * Ambient client execution device and browser context.
+ *
+ * @example
+ * const ctx: DeviceContext = {
+ *   userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...',
+ *   currentUrl: 'https://app.example.com/checkout',
+ *   viewport: '1920x1080',
+ *   networkStatus: '4g',
+ *   timezone: 'Asia/Ho_Chi_Minh',
+ * };
+ */
+export interface DeviceContext {
+  /** Browser User-Agent string. */
+  userAgent: string;
+  /** Client operating system name and version. */
+  os?: string;
+  /** Browser name and version. */
+  browser?: string;
+  /** Viewport dimensions (e.g. "1920x1080"). */
+  viewport?: string;
+  /** Current browser window URL where error occurred. */
+  currentUrl: string;
+  /** Network connectivity condition (e.g. "4g", "wifi", "online"). */
+  networkStatus?: string;
+  /** Client timezone (e.g. "Asia/Ho_Chi_Minh"). */
+  timezone?: string;
+}
+
+/**
+ * Ingestion payload dispatched from @nexus/tracker to Go-Gin edge.
+ *
+ * @example
+ * const payload: ErrorEventPayload = {
+ *   fingerprint: 'sha256hex...',
+ *   errorType: 'TypeError',
+ *   errorMessage: "Cannot read properties of undefined (reading 'map')",
+ *   stackTrace: [{ functionName: 'ProductList', fileName: 'chunk.js', lineNumber: 1, columnNumber: 400 }],
+ *   breadcrumbs: [],
+ *   deviceContext: { userAgent: 'Mozilla/5.0...', currentUrl: '/products' },
+ *   occurrenceCount: 1,
+ *   clientTimestamp: 1704067200000,
+ * };
+ */
+export interface ErrorEventPayload {
+  /**
+   * Deterministic hash representing this specific class of crash.
+   * Format: sha256(errorType + ":" + errorMessage + ":" + topFrameFile + ":" + topFrameLine)
+   */
+  fingerprint: string;
+  /** JavaScript error type (e.g. "TypeError", "ReferenceError", "UnhandledRejection"). */
+  errorType: string;
+  /** Primary error message string. */
+  errorMessage: string;
+  /** Parsed stack trace frames from innermost to outermost. */
+  stackTrace: StackFrame[];
+  /** Chronological ring-buffer trail of events prior to crash (max 20). */
+  breadcrumbs: Breadcrumb[];
+  /** End-user context at time of crash (sanitized before transmission). */
+  userContext?: UserContext;
+  /** Client environment context. */
+  deviceContext: DeviceContext;
+  /** Key-value metadata tags for search aggregation. */
+  tags?: Record<string, string>;
+  /**
+   * Counter tracking consecutive duplicate occurrences aggregated by client.
+   * Prevents infinite loop crash cascades from overwhelming ingestion.
+   */
+  occurrenceCount: number;
+  /** Client-side epoch timestamp in milliseconds when error was captured. */
+  clientTimestamp: number;
+}
+
+/**
+ * Persistent error event record stored in PostgreSQL and returned to Shell UI.
+ *
+ * @example
+ * const entity: ErrorEventEntity = {
+ *   ...payload,
+ *   id: 'uuid-v4',
+ *   projectId: 'project-uuid',
+ *   environment: 'production',
+ *   serverReceivedAt: '2024-01-01T00:00:05Z',
+ * };
+ */
+export interface ErrorEventEntity extends ErrorEventPayload {
+  /** Unique UUID v4 identifier. */
+  id: string;
+  /** Project UUID v4 identifier. */
+  projectId: string;
+  /** Target deployment environment. */
+  environment: Environment;
+  /** Timestamp when Go-Gin successfully processed and recorded the event. */
+  serverReceivedAt: string;
+}
+
+/**
+ * Aggregated error group item displayed on the Console Dashboard.
+ *
+ * @example
+ * const group: ErrorGroupSummary = {
+ *   fingerprint: 'sha256hex...',
+ *   errorType: 'TypeError',
+ *   errorMessage: "Cannot read properties of undefined (reading 'map')",
+ *   environment: 'production',
+ *   totalCount: 1547,
+ *   affectedUsersCount: 234,
+ *   firstSeenAt: '2024-01-01T10:00:00Z',
+ *   lastSeenAt: '2024-06-15T14:32:01Z',
+ * };
+ */
+export interface ErrorGroupSummary {
+  /** Fingerprint common to all events in this group. */
+  fingerprint: string;
+  /** Error type classification. */
+  errorType: string;
+  /** Primary error message. */
+  errorMessage: string;
+  /** Environment where errors occurred. */
+  environment: Environment;
+  /** Total sum of crash occurrences across all end-users. */
+  totalCount: number;
+  /** Count of unique users impacted by this crash group. */
+  affectedUsersCount: number;
+  /** Timestamp of the first time this crash was ever seen. */
+  firstSeenAt: string;
+  /** Timestamp of the latest crash occurrence. */
+  lastSeenAt: string;
+}
+
+// Re-export UserContext for downstream consumers of @nexus/contracts/tracker
+export type { UserContext };

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: ['src/index.ts', 'src/auth.ts', 'src/flags.ts', 'src/tracker.ts', 'src/rfc7807.ts'],
+  format: ['esm', 'cjs'],
+  dts: true,
+  splitting: false,
+  sourcemap: true,
+  clean: true,
+  treeshake: true,
+  target: 'es2022',
+  outExtension({ format }) {
+    return {
+      js: format === 'esm' ? '.mjs' : '.cjs',
+    };
+  },
+});