@nexussdk/contracts 0.0.1 → 0.0.4

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;