@nexussdk/contracts 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,32 @@
+# @nexussdk/contracts
+
+Single Source of Truth (SSOT) data contracts and TypeScript interfaces for the **Nexus Platform** ecosystem.
+
+[![npm version](https://img.shields.io/npm/v/@nexussdk/contracts.svg)](https://www.npmjs.com/package/@nexussdk/contracts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Installation
+
+```bash
+npm install @nexussdk/contracts
+# or
+pnpm add @nexussdk/contracts
+```
+
+---
+
+## Exports
+
+- `@nexussdk/contracts`: Root unified types
+- `@nexussdk/contracts/flags`: Feature flag, evaluation rule, and rollout segment definitions
+- `@nexussdk/contracts/tracker`: Telemetry event, breadcrumb, and exception payload interfaces
+- `@nexussdk/contracts/auth`: Client key and environment metadata definitions
+- `@nexussdk/contracts/rfc7807`: Problem Details standard error structures
+
+---
+
+## License
+
+MIT © [Nexus Platform](https://github.com/Huynhdung295/NexusSDK)

package/dist/auth.cjs

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

package/dist/auth.mjs

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

package/dist/flags.cjs

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

package/dist/flags.mjs

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

package/dist/index.cjs

@@ -1,8 +1,2 @@
-'use strict';
-
-// src/rfc7807.ts
-var NEXUS_ERROR_BASE = "https://nexus.dev/errors";
-
-exports.NEXUS_ERROR_BASE = NEXUS_ERROR_BASE;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map
+'use strict';var t="https://nexus.dev/errors";
+exports.NEXUS_ERROR_BASE=t;

package/dist/index.mjs

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

package/dist/rfc7807.cjs

@@ -1,8 +1,2 @@
-'use strict';
-
-// src/rfc7807.ts
-var NEXUS_ERROR_BASE = "https://nexus.dev/errors";
-
-exports.NEXUS_ERROR_BASE = NEXUS_ERROR_BASE;
-//# sourceMappingURL=rfc7807.cjs.map
-//# sourceMappingURL=rfc7807.cjs.map
+'use strict';var t="https://nexus.dev/errors";
+exports.NEXUS_ERROR_BASE=t;

package/dist/rfc7807.mjs

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

package/dist/tracker.cjs

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

package/dist/tracker.mjs

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

package/package.json

@@ -1,11 +1,39 @@
 {
   "name": "@nexussdk/contracts",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "description": "Single Source of Truth (SSOT) data contracts for the Nexus Platform ecosystem",
+  "license": "MIT",
+  "author": "Nexus",
+  "contributors": [
+    {
+      "name": "Hồ Huỳnh Dũng",
+      "email": "hohuynhdung@gmail.com",
+      "url": "https://github.com/Huynhdung295"
+    }
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Huynhdung295/NexusSDK.git",
+    "directory": "packages/contracts"
+  },
+  "homepage": "https://github.com/Huynhdung295/NexusSDK#readme",
+  "keywords": [
+    "nexus",
+    "nexussdk",
+    "contracts",
+    "typescript",
+    "feature-flags",
+    "telemetry",
+    "rfc7807"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",

package/.turbo/turbo-build.log

@@ -1,52 +0,0 @@
-
-> @nexussdk/contracts@0.0.1 build /home/runner/work/NexusSDK/NexusSDK/packages/contracts
-> tsup
-
-CLI Building entry: src/auth.ts, src/flags.ts, src/index.ts, src/rfc7807.ts, src/tracker.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/NexusSDK/NexusSDK/packages/contracts/tsup.config.ts
-CLI Target: es2022
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-Generated an empty chunk: "auth".
-Generated an empty chunk: "flags".
-Generated an empty chunk: "tracker".
-Generated an empty chunk: "auth".
-Generated an empty chunk: "flags".
-Generated an empty chunk: "tracker".
-CJS dist/auth.cjs        82.00 B
-CJS dist/flags.cjs       84.00 B
-CJS dist/index.cjs       199.00 B
-CJS dist/rfc7807.cjs     203.00 B
-CJS dist/tracker.cjs     88.00 B
-CJS dist/auth.cjs.map    69.00 B
-CJS dist/flags.cjs.map   70.00 B
-CJS dist/index.cjs.map   2.58 KB
-CJS dist/rfc7807.cjs.map 2.58 KB
-CJS dist/tracker.cjs.map 72.00 B
-CJS ⚡️ Build success in 111ms
-ESM dist/auth.mjs        68.00 B
-ESM dist/flags.mjs       70.00 B
-ESM dist/index.mjs       168.00 B
-ESM dist/rfc7807.mjs     172.00 B
-ESM dist/tracker.mjs     74.00 B
-ESM dist/auth.mjs.map    69.00 B
-ESM dist/flags.mjs.map   70.00 B
-ESM dist/index.mjs.map   2.57 KB
-ESM dist/rfc7807.mjs.map 2.58 KB
-ESM dist/tracker.mjs.map 72.00 B
-ESM ⚡️ Build success in 113ms
-DTS Build start
-DTS ⚡️ Build success in 1002ms
-DTS dist/index.d.mts   607.00 B
-DTS dist/rfc7807.d.mts 2.49 KB
-DTS dist/tracker.d.mts 6.48 KB
-DTS dist/flags.d.mts   7.17 KB
-DTS dist/auth.d.mts    6.21 KB
-DTS dist/index.d.ts    603.00 B
-DTS dist/rfc7807.d.ts  2.49 KB
-DTS dist/tracker.d.ts  6.48 KB
-DTS dist/flags.d.ts    7.17 KB
-DTS dist/auth.d.ts     6.21 KB

package/dist/auth.cjs.map

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

package/dist/auth.mjs.map

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

package/dist/flags.cjs.map

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

package/dist/flags.mjs.map

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

package/dist/index.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/rfc7807.ts"],"names":[],"mappings":";;;AA2EO,IAAM,gBAAA,GAAmB","file":"index.cjs","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/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/rfc7807.ts"],"names":[],"mappings":";AA2EO,IAAM,gBAAA,GAAmB","file":"index.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/rfc7807.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/rfc7807.ts"],"names":[],"mappings":";;;AA2EO,IAAM,gBAAA,GAAmB","file":"rfc7807.cjs","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/rfc7807.mjs.map

@@ -1 +0,0 @@
-{"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.map

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

package/dist/tracker.mjs.map

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

package/src/auth.ts

@@ -1,224 +0,0 @@
-/**
- * @fileoverview Authentication, Organization, Project, and API Key contracts.
- * Governs multi-tenant B2B2C security and quota boundaries.
- * @module @nexus/contracts/auth
- */
-
-/**
- * Subscription plan tiers determining rate limits and feature entitlements.
- * @example
- * const tier: PlanTier = 'PRO';
- */
-export type PlanTier = 'FREE' | 'PRO' | 'ENTERPRISE';
-
-/**
- * Operational status of a tenant account.
- * @example
- * const status: AccountStatus = 'ACTIVE';
- */
-export type AccountStatus = 'ACTIVE' | 'SUSPENDED' | 'CANCELLED';
-
-/**
- * Deployment environments for project isolation.
- * @example
- * const env: Environment = 'production';
- */
-export type Environment = 'development' | 'staging' | 'production';
-
-/**
- * Cryptographic API Key permission scope.
- * - `PUBLIC`: Embedded in client browsers. Permitted only for flag evaluation,
- *   SSE subscriptions, and error ingestion.
- * - `SECRET`: Secure server-side only. Full administrative CRUD operations.
- * @example
- * const keyType: ApiKeyType = 'PUBLIC';
- */
-export type ApiKeyType = 'PUBLIC' | 'SECRET';
-
-/**
- * Represents a developer or organization account (Tenant).
- *
- * @example
- * const account: Account = {
- *   id: 'uuid-v4',
- *   name: 'Acme Corp',
- *   email: 'admin@acme.com',
- *   planTier: 'PRO',
- *   status: 'ACTIVE',
- *   createdAt: '2024-01-01T00:00:00Z',
- *   updatedAt: '2024-06-01T00:00:00Z',
- * };
- */
-export interface Account {
-  /** Unique UUID v4 identifier. */
-  id: string;
-  /** Organization or developer display name. */
-  name: string;
-  /** Primary contact and authentication email. */
-  email: string;
-  /** Current billing entitlement tier. */
-  planTier: PlanTier;
-  /** Current operational state. */
-  status: AccountStatus;
-  /** Arbitrary organizational metadata. */
-  metadata?: Record<string, unknown>;
-  /** Timestamp when account was created. */
-  createdAt: string;
-  /** Timestamp when account was last modified. */
-  updatedAt: string;
-}
-
-/**
- * Represents an isolated application owned by an Account.
- *
- * @example
- * const project: Project = {
- *   id: 'uuid-v4',
- *   accountId: 'account-uuid-v4',
- *   name: 'My App',
- *   slug: 'my-app',
- *   createdAt: '2024-01-01T00:00:00Z',
- *   updatedAt: '2024-06-01T00:00:00Z',
- * };
- */
-export interface Project {
-  /** Unique UUID v4 identifier. */
-  id: string;
-  /** Owning Account UUID v4 identifier. */
-  accountId: string;
-  /** Human-readable project name. */
-  name: string;
-  /** URL-friendly unique slug under the parent account. */
-  slug: string;
-  /** Project description. */
-  description?: string;
-  /** Timestamp of project creation. */
-  createdAt: string;
-  /** Timestamp of last modification. */
-  updatedAt: string;
-}
-
-/**
- * Public or Secret API Key metadata used by Go-Gin and NestJS guards.
- *
- * @example
- * const apiKey: ApiKey = {
- *   id: 'uuid-v4',
- *   projectId: 'project-uuid-v4',
- *   environment: 'production',
- *   keyType: 'PUBLIC',
- *   keyPrefix: 'pk_live_a1b2',
- *   keyHash: 'sha256hexstring...',
- *   allowedDomains: ['https://mybrand.com'],
- *   rateLimitPerMin: 1000,
- *   monthlyEventsLimit: 100000,
- *   currentMonthUsage: 4250,
- *   usageResetAt: '2024-07-01T00:00:00Z',
- *   isActive: true,
- *   createdAt: '2024-01-01T00:00:00Z',
- * };
- */
-export interface ApiKey {
-  /** Unique UUID v4 identifier. */
-  id: string;
-  /** Parent Project identifier. */
-  projectId: string;
-  /** Target deployment environment. */
-  environment: Environment;
-  /** Key capability level. */
-  keyType: ApiKeyType;
-  /** Public preview prefix (e.g. "pk_live_abcd1234"). Raw secret is never persisted. */
-  keyPrefix: string;
-  /** SHA-256 hash string (64 chars) matching stored database records. */
-  keyHash: string;
-  /** Whitelisted Origin domains for browser CORS security (e.g. ["https://mybrand.com"]). */
-  allowedDomains: string[];
-  /** Maximum allowed HTTP requests per minute. */
-  rateLimitPerMin: number;
-  /** Hard cap for error and event ingestion per calendar month. */
-  monthlyEventsLimit: number;
-  /** Current count of events processed in the active billing window. */
-  currentMonthUsage: number;
-  /** Timestamp when the current billing usage cycle resets. */
-  usageResetAt: string;
-  /** Flag toggle allowing immediate key revocation. */
-  isActive: boolean;
-  /** Timestamp when the key was last used in any API request. */
-  lastUsedAt?: string;
-  /** Creation timestamp. */
-  createdAt: string;
-}
-
-/**
- * Payload returned to the developer upon key generation.
- * This is the ONLY time the raw token is made visible.
- *
- * @example
- * const response: GeneratedApiKeyResponse = {
- *   apiKey: { ... },
- *   rawKey: 'pk_live_a1b2c3d4e5f6...',
- * };
- */
-export interface GeneratedApiKeyResponse {
-  /** Public or Secret key metadata entity. */
-  apiKey: ApiKey;
-  /**
-   * Plaintext unhashed API key string (e.g., 'pk_live_a1b2c3...').
-   * Must be securely copied by developer; cannot be recovered after this response.
-   */
-  rawKey: string;
-}
-
-/**
- * DTO for account registration requests.
- *
- * @example
- * const dto: RegisterAccountDto = {
- *   name: 'Acme Corp',
- *   email: 'admin@acme.com',
- *   password: 'S3cur3P@ssw0rd!',
- * };
- */
-export interface RegisterAccountDto {
-  /** Organization display name. */
-  name: string;
-  /** Primary contact email. */
-  email: string;
-  /** Plaintext password (hashed server-side with bcrypt). */
-  password: string;
-}
-
-/**
- * DTO for login requests.
- *
- * @example
- * const dto: LoginDto = {
- *   email: 'admin@acme.com',
- *   password: 'S3cur3P@ssw0rd!',
- * };
- */
-export interface LoginDto {
-  /** Registered email address. */
-  email: string;
-  /** Plaintext password to verify against stored bcrypt hash. */
-  password: string;
-}
-
-/**
- * Session payload embedded in JWT and HttpOnly cookies.
- *
- * @example
- * const session: SessionPayload = {
- *   accountId: 'uuid-v4',
- *   email: 'admin@acme.com',
- *   planTier: 'PRO',
- * };
- */
-export interface SessionPayload {
-  /** Authenticated account's UUID. */
-  accountId: string;
-  /** Authenticated account's email. */
-  email: string;
-  /** Plan tier for feature entitlement checks. */
-  planTier: PlanTier;
-}

package/src/flags.ts

@@ -1,255 +0,0 @@
-/**
- * @fileoverview Feature Flagging, Dynamic Configuration, and ABAC Targeting contracts.
- * @module @nexus/contracts/flags
- */
-
-import type { Environment } from './auth.js';
-
-/**
- * Attribute evaluation operators for Attribute-Based Access Control (ABAC).
- * Used in {@link TargetingRule} to compare user context values against flag targets.
- *
- * @example
- * const op: RuleOperator = 'IN';
- */
-export type RuleOperator =
-  | 'EQUALS'
-  | 'NOT_EQUALS'
-  | 'CONTAINS'
-  | 'NOT_CONTAINS'
-  | 'IN'
-  | 'NOT_IN'
-  | 'STARTS_WITH'
-  | 'ENDS_WITH'
-  | 'GREATER_THAN'
-  | 'LESS_THAN'
-  | 'SEMVER_GTE'
-  | 'SEMVER_LTE';
-
-/**
- * Atomic rule evaluating a single user attribute against target values.
- *
- * @example
- * const rule: TargetingRule = {
- *   attribute: 'country',
- *   operator: 'IN',
- *   values: ['VN', 'SG', 'TH'],
- * };
- */
-export interface TargetingRule {
-  /** Attribute path in UserContext (e.g. "country", "tier", "appVersion"). */
-  attribute: string;
-  /** Logical operator applied to the attribute. */
-  operator: RuleOperator;
-  /** Comparison targets (strings, numbers, or arrays). */
-  values: Array<string | number | boolean>;
-}
-
-/**
- * Primitive types permissible inside dynamic configuration variants.
- */
-export type VariantValue = string | number | boolean | Record<string, unknown> | unknown[];
-
-/**
- * Remote Configuration variants dictionary.
- *
- * @example
- * const variants: FlagVariants = {
- *   button_color: '#FF0055',
- *   max_items: 25,
- *   theme: 'dark',
- * };
- */
-export type FlagVariants = Record<string, VariantValue>;
-
-/**
- * Represents a Feature Flag entity stored in the platform.
- *
- * @example
- * const flag: FeatureFlag = {
- *   id: 'uuid-v4',
- *   projectId: 'project-uuid',
- *   environment: 'production',
- *   key: 'checkout_v2',
- *   name: 'Checkout Redesign V2',
- *   isEnabled: true,
- *   rolloutPercentage: 50,
- *   targetingRules: [],
- *   variants: { show_express: true },
- *   version: 3,
- *   createdAt: '2024-01-01T00:00:00Z',
- *   updatedAt: '2024-06-01T00:00:00Z',
- * };
- */
-export interface FeatureFlag {
-  /** Unique UUID v4 identifier. */
-  id: string;
-  /** Owning Project UUID v4 identifier. */
-  projectId: string;
-  /** Deployment environment. */
-  environment: Environment;
-  /** Unique programmatic identifier (e.g. "checkout_v2"). */
-  key: string;
-  /** Human-readable flag name. */
-  name: string;
-  /** Optional purpose explanation. */
-  description?: string;
-  /** Master kill-switch. When false, flag immediately resolves to fallback/false. */
-  isEnabled: boolean;
-  /**
-   * Percentage rollout integer (0 to 100).
-   * Computed deterministically via MurmurHash3(userId + flagKey).
-   */
-  rolloutPercentage: number;
-  /** Ordered list of targeting rules. Must satisfy all rules for flag to apply. */
-  targetingRules: TargetingRule[];
-  /** Remote dynamic configuration key-value pairs attached to this flag. */
-  variants: FlagVariants;
-  /** Monotonically increasing schema version for cache invalidation. */
-  version: number;
-  /** Creation timestamp. */
-  createdAt: string;
-  /** Last modification timestamp. */
-  updatedAt: string;
-}
-
-/**
- * End-user contextual data supplied by Client SDK for rule evaluation.
- *
- * @example
- * const user: UserContext = {
- *   id: 'usr_12345',
- *   email: 'john@example.com',
- *   country: 'VN',
- *   appVersion: '2.4.1',
- *   custom: { tier: 'premium', vipMember: true },
- * };
- */
-export interface UserContext {
-  /**
-   * Unique user identifier (e.g. "usr_12345").
-   * Crucial for consistent percentage rollout bucketing.
-   * If omitted, SDK must fallback to anonymous persistent device UUID.
-   */
-  id?: string;
-  /** User email (commonly used for beta targeting). */
-  email?: string;
-  /** Two-letter ISO country code (e.g. "VN", "US"). */
-  country?: string;
-  /** Client application version (e.g. "2.4.1") for semver targeting. */
-  appVersion?: string;
-  /** Arbitrary custom attributes for ABAC rules. */
-  custom?: Record<string, string | number | boolean>;
-}
-
-/**
- * Evaluation output generated for a single flag.
- *
- * @example
- * const result: FlagEvaluationResult = {
- *   key: 'checkout_v2',
- *   enabled: true,
- *   variants: { show_express: true },
- *   reason: 'ROLLOUT_MATCH',
- *   version: 3,
- * };
- */
-export interface FlagEvaluationResult {
-  /** Flag unique key. */
-  key: string;
-  /** Final boolean active status. */
-  enabled: boolean;
-  /** Selected dynamic configuration variants (empty if disabled). */
-  variants: FlagVariants;
-  /** Explanation string of evaluation outcome. */
-  reason: 'TARGETING_MATCH' | 'ROLLOUT_MATCH' | 'DEFAULT_ENABLED' | 'KILL_SWITCH' | 'FALLBACK';
-  /** Schema version of the flag when evaluated. */
-  version: number;
-}
-
-/**
- * Map of multiple evaluated flags returned in single batch request.
- *
- * @example
- * const batch: BatchFlagEvaluation = {
- *   checkout_v2: { key: 'checkout_v2', enabled: true, variants: {}, reason: 'ROLLOUT_MATCH', version: 1 },
- *   dark_mode: { key: 'dark_mode', enabled: false, variants: {}, reason: 'KILL_SWITCH', version: 2 },
- * };
- */
-export type BatchFlagEvaluation = Record<string, FlagEvaluationResult>;
-
-/**
- * Real-time SSE payload pushed from Go-Gin to Client SDKs when a flag is updated.
- *
- * @example
- * const event: FlagStreamEvent = {
- *   type: 'FLAG_UPDATE',
- *   key: 'checkout_v2',
- *   data: { key: 'checkout_v2', enabled: true, variants: {}, reason: 'DEFAULT_ENABLED', version: 4 },
- *   timestamp: 1704067200000,
- * };
- */
-export interface FlagStreamEvent {
-  /** Event classification. */
-  type: 'FLAG_UPDATE' | 'FLAG_DELETE' | 'HEARTBEAT';
-  /** Flag key modified. */
-  key: string;
-  /** Fresh evaluation payload or null on deletion. */
-  data?: FlagEvaluationResult;
-  /** Server timestamp of dispatch in milliseconds epoch. */
-  timestamp: number;
-}
-
-/**
- * DTO for creating a new feature flag.
- *
- * @example
- * const dto: CreateFlagDto = {
- *   key: 'new_checkout',
- *   name: 'New Checkout',
- *   environment: 'development',
- *   rolloutPercentage: 0,
- *   variants: {},
- *   targetingRules: [],
- * };
- */
-export interface CreateFlagDto {
-  /** Unique programmatic identifier. */
-  key: string;
-  /** Human-readable display name. */
-  name: string;
-  /** Target environment. */
-  environment: Environment;
-  /** Optional description. */
-  description?: string;
-  /** Initial rollout percentage. */
-  rolloutPercentage: number;
-  /** Initial variants. */
-  variants: FlagVariants;
-  /** Initial targeting rules. */
-  targetingRules: TargetingRule[];
-}
-
-/**
- * DTO for updating an existing feature flag (all fields optional).
- *
- * @example
- * const dto: UpdateFlagDto = {
- *   isEnabled: true,
- *   rolloutPercentage: 75,
- * };
- */
-export interface UpdateFlagDto {
-  /** Optional new display name. */
-  name?: string;
-  /** Optional new description. */
-  description?: string;
-  /** Toggle kill-switch state. */
-  isEnabled?: boolean;
-  /** New rollout percentage (0–100). */
-  rolloutPercentage?: number;
-  /** Updated targeting rules array. */
-  targetingRules?: TargetingRule[];
-  /** Updated variants map. */
-  variants?: FlagVariants;
-}

package/src/index.ts

@@ -1,12 +0,0 @@
-/**
- * @fileoverview Main entry point for @nexussdk/contracts.
- * Re-exports all contract modules: flags, tracker, auth, and RFC 7807 problem details.
- *
- * @example
- * import { FeatureFlag, ProblemDetails, ErrorEventPayload } from '@nexussdk/contracts';
- */
-
-export * from './auth.js';
-export * from './flags.js';
-export * from './tracker.js';
-export * from './rfc7807.js';

package/src/rfc7807.ts

@@ -1,76 +0,0 @@
-/**
- * @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',
- * };
- */
-export 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`;
- */
-export const NEXUS_ERROR_BASE = 'https://nexus.dev/errors' as const;

package/src/tracker.ts

@@ -1,205 +0,0 @@
-/**
- * @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

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

package/tsup.config.ts

@@ -1,17 +0,0 @@
-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',
-    };
-  },
-});