@nexussdk/contracts 0.0.1

package/dist/rfc7807.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @fileoverview Problem Details for HTTP APIs Specification (RFC 7807).
+ * Standardized error format across Go-Gin and NestJS error responses.
+ * @see {@link https://www.rfc-editor.org/rfc/rfc7807}
+ * @module @nexus/contracts/rfc7807
+ */
+/**
+ * RFC 7807 Compliant Error Schema.
+ * Ensures consistent machine-readable error diagnostics across all Nexus services.
+ *
+ * @example
+ * const problem: ProblemDetails = {
+ *   type: 'https://nexus.dev/errors/quota-exceeded',
+ *   title: 'Monthly Quota Exceeded',
+ *   status: 429,
+ *   detail: "API Key 'pk_live_...' has exhausted its limit of 50,000 monthly events.",
+ *   instance: '/api/v1/telemetry/errors',
+ *   timestamp: '2024-06-01T12:00:00Z',
+ * };
+ */
+interface ProblemDetails {
+    /**
+     * URI reference identifying the problem type.
+     * Should be a stable, documented URI that clients can bookmark.
+     * @example 'https://nexus.dev/errors/rate-limit-exceeded'
+     */
+    type: string;
+    /**
+     * Short, human-readable summary of problem type.
+     * Must be invariant across occurrences of the same problem type.
+     * @example 'Too Many Requests'
+     */
+    title: string;
+    /**
+     * HTTP status code generated by origin server.
+     * @example 429
+     */
+    status: number;
+    /**
+     * Human-readable explanation specific to this occurrence of the problem.
+     * May differ across occurrences of the same problem type.
+     * @example "API Key 'pk_live_a1b2...' has exhausted its monthly event limit."
+     */
+    detail: string;
+    /**
+     * URI reference identifying specific occurrence of problem.
+     * Typically the request path that triggered the error.
+     * @example '/api/v1/telemetry/errors'
+     */
+    instance?: string;
+    /**
+     * Additional diagnostic error parameters for validation failures.
+     * @example [{ name: 'email', reason: 'Must be a valid email address.' }]
+     */
+    invalidParams?: Array<{
+        /** Field name that caused the validation error. */
+        name: string;
+        /** Human-readable reason for the validation failure. */
+        reason: string;
+    }>;
+    /**
+     * ISO 8601 timestamp when error was produced.
+     * @example '2024-06-01T12:00:00.000Z'
+     */
+    timestamp?: string;
+}
+/**
+ * Standard Nexus error type URI prefix.
+ * All RFC 7807 type values should use this base to ensure namespacing consistency.
+ *
+ * @example
+ * const type = `${NEXUS_ERROR_BASE}/rate-limit-exceeded`;
+ */
+declare const NEXUS_ERROR_BASE: "https://nexus.dev/errors";
+
+export { NEXUS_ERROR_BASE, type ProblemDetails };

package/dist/rfc7807.mjs

@@ -0,0 +1,6 @@
+// src/rfc7807.ts
+var NEXUS_ERROR_BASE = "https://nexus.dev/errors";
+
+export { NEXUS_ERROR_BASE };
+//# sourceMappingURL=rfc7807.mjs.map
+//# sourceMappingURL=rfc7807.mjs.map

package/dist/rfc7807.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/rfc7807.ts"],"names":[],"mappings":";AA2EO,IAAM,gBAAA,GAAmB","file":"rfc7807.mjs","sourcesContent":["/**\n * @fileoverview Problem Details for HTTP APIs Specification (RFC 7807).\n * Standardized error format across Go-Gin and NestJS error responses.\n * @see {@link https://www.rfc-editor.org/rfc/rfc7807}\n * @module @nexus/contracts/rfc7807\n */\n\n/**\n * RFC 7807 Compliant Error Schema.\n * Ensures consistent machine-readable error diagnostics across all Nexus services.\n *\n * @example\n * const problem: ProblemDetails = {\n *   type: 'https://nexus.dev/errors/quota-exceeded',\n *   title: 'Monthly Quota Exceeded',\n *   status: 429,\n *   detail: \"API Key 'pk_live_...' has exhausted its limit of 50,000 monthly events.\",\n *   instance: '/api/v1/telemetry/errors',\n *   timestamp: '2024-06-01T12:00:00Z',\n * };\n */\nexport interface ProblemDetails {\n  /**\n   * URI reference identifying the problem type.\n   * Should be a stable, documented URI that clients can bookmark.\n   * @example 'https://nexus.dev/errors/rate-limit-exceeded'\n   */\n  type: string;\n  /**\n   * Short, human-readable summary of problem type.\n   * Must be invariant across occurrences of the same problem type.\n   * @example 'Too Many Requests'\n   */\n  title: string;\n  /**\n   * HTTP status code generated by origin server.\n   * @example 429\n   */\n  status: number;\n  /**\n   * Human-readable explanation specific to this occurrence of the problem.\n   * May differ across occurrences of the same problem type.\n   * @example \"API Key 'pk_live_a1b2...' has exhausted its monthly event limit.\"\n   */\n  detail: string;\n  /**\n   * URI reference identifying specific occurrence of problem.\n   * Typically the request path that triggered the error.\n   * @example '/api/v1/telemetry/errors'\n   */\n  instance?: string;\n  /**\n   * Additional diagnostic error parameters for validation failures.\n   * @example [{ name: 'email', reason: 'Must be a valid email address.' }]\n   */\n  invalidParams?: Array<{\n    /** Field name that caused the validation error. */\n    name: string;\n    /** Human-readable reason for the validation failure. */\n    reason: string;\n  }>;\n  /**\n   * ISO 8601 timestamp when error was produced.\n   * @example '2024-06-01T12:00:00.000Z'\n   */\n  timestamp?: string;\n}\n\n/**\n * Standard Nexus error type URI prefix.\n * All RFC 7807 type values should use this base to ensure namespacing consistency.\n *\n * @example\n * const type = `${NEXUS_ERROR_BASE}/rate-limit-exceeded`;\n */\nexport const NEXUS_ERROR_BASE = 'https://nexus.dev/errors' as const;\n"]}

package/dist/tracker.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=tracker.cjs.map
+//# sourceMappingURL=tracker.cjs.map

package/dist/tracker.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"tracker.cjs"}

package/dist/tracker.d.mts

@@ -0,0 +1,197 @@
+import { Environment } from './auth.mjs';
+import { UserContext } from './flags.mjs';
+
+/**
+ * @fileoverview Telemetry, Breadcrumb Tracing, and Error Ingestion contracts.
+ * @module @nexus/contracts/tracker
+ */
+
+/**
+ * Severity level of captured telemetry events.
+ *
+ * @example
+ * const level: SeverityLevel = 'error';
+ */
+type SeverityLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+/**
+ * Categorization of user action trails leading to a crash.
+ *
+ * @example
+ * const category: BreadcrumbCategory = 'ui.click';
+ */
+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' },
+ * };
+ */
+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,
+ * };
+ */
+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',
+ * };
+ */
+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,
+ * };
+ */
+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',
+ * };
+ */
+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',
+ * };
+ */
+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;
+}
+
+export { type Breadcrumb, type BreadcrumbCategory, type DeviceContext, type ErrorEventEntity, type ErrorEventPayload, type ErrorGroupSummary, type SeverityLevel, type StackFrame, UserContext };

package/dist/tracker.d.ts

@@ -0,0 +1,197 @@
+import { Environment } from './auth.js';
+import { UserContext } from './flags.js';
+
+/**
+ * @fileoverview Telemetry, Breadcrumb Tracing, and Error Ingestion contracts.
+ * @module @nexus/contracts/tracker
+ */
+
+/**
+ * Severity level of captured telemetry events.
+ *
+ * @example
+ * const level: SeverityLevel = 'error';
+ */
+type SeverityLevel = 'debug' | 'info' | 'warning' | 'error' | 'fatal';
+/**
+ * Categorization of user action trails leading to a crash.
+ *
+ * @example
+ * const category: BreadcrumbCategory = 'ui.click';
+ */
+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' },
+ * };
+ */
+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,
+ * };
+ */
+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',
+ * };
+ */
+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,
+ * };
+ */
+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',
+ * };
+ */
+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',
+ * };
+ */
+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;
+}
+
+export { type Breadcrumb, type BreadcrumbCategory, type DeviceContext, type ErrorEventEntity, type ErrorEventPayload, type ErrorGroupSummary, type SeverityLevel, type StackFrame, UserContext };

package/dist/tracker.mjs

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=tracker.mjs.map
+//# sourceMappingURL=tracker.mjs.map

package/dist/tracker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"tracker.mjs"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nexussdk/contracts",
+  "version": "0.0.1",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Single Source of Truth (SSOT) data contracts for the Nexus Platform ecosystem",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./flags": {
+      "types": "./dist/flags.d.ts",
+      "import": "./dist/flags.mjs",
+      "require": "./dist/flags.cjs"
+    },
+    "./tracker": {
+      "types": "./dist/tracker.d.ts",
+      "import": "./dist/tracker.mjs",
+      "require": "./dist/tracker.cjs"
+    },
+    "./auth": {
+      "types": "./dist/auth.d.ts",
+      "import": "./dist/auth.mjs",
+      "require": "./dist/auth.cjs"
+    },
+    "./rfc7807": {
+      "types": "./dist/rfc7807.d.ts",
+      "import": "./dist/rfc7807.mjs",
+      "require": "./dist/rfc7807.cjs"
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "rimraf": "^5.0.5"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "clean": "rimraf dist"
+  }
+}