@nexussdk/contracts 0.0.1

package/dist/flags.d.mts

@@ -0,0 +1,235 @@
+import { Environment } from './auth.mjs';
+
+/**
+ * @fileoverview Feature Flagging, Dynamic Configuration, and ABAC Targeting contracts.
+ * @module @nexus/contracts/flags
+ */
+
+/**
+ * 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';
+ */
+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'],
+ * };
+ */
+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.
+ */
+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',
+ * };
+ */
+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',
+ * };
+ */
+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 },
+ * };
+ */
+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,
+ * };
+ */
+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 },
+ * };
+ */
+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,
+ * };
+ */
+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: [],
+ * };
+ */
+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,
+ * };
+ */
+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;
+}
+
+export type { BatchFlagEvaluation, CreateFlagDto, FeatureFlag, FlagEvaluationResult, FlagStreamEvent, FlagVariants, RuleOperator, TargetingRule, UpdateFlagDto, UserContext, VariantValue };

package/dist/flags.d.ts

@@ -0,0 +1,235 @@
+import { Environment } from './auth.js';
+
+/**
+ * @fileoverview Feature Flagging, Dynamic Configuration, and ABAC Targeting contracts.
+ * @module @nexus/contracts/flags
+ */
+
+/**
+ * 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';
+ */
+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'],
+ * };
+ */
+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.
+ */
+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',
+ * };
+ */
+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',
+ * };
+ */
+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 },
+ * };
+ */
+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,
+ * };
+ */
+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 },
+ * };
+ */
+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,
+ * };
+ */
+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: [],
+ * };
+ */
+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,
+ * };
+ */
+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;
+}
+
+export type { BatchFlagEvaluation, CreateFlagDto, FeatureFlag, FlagEvaluationResult, FlagStreamEvent, FlagVariants, RuleOperator, TargetingRule, UpdateFlagDto, UserContext, VariantValue };

package/dist/flags.mjs

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

package/dist/flags.mjs.map

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

package/dist/index.cjs

@@ -0,0 +1,8 @@
+'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

package/dist/index.cjs.map

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

@@ -0,0 +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 { NEXUS_ERROR_BASE, ProblemDetails } from './rfc7807.mjs';

package/dist/index.d.ts

@@ -0,0 +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 { NEXUS_ERROR_BASE, ProblemDetails } from './rfc7807.js';

package/dist/index.mjs

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

package/dist/index.mjs.map

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

@@ -0,0 +1,8 @@
+'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

package/dist/rfc7807.cjs.map

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

@@ -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 };