servcraft 0.1.0 → 0.1.1

package/src/modules/feature-flag/types.ts

@@ -0,0 +1,192 @@
+export type FlagStatus = 'enabled' | 'disabled';
+export type FlagStrategy = 'boolean' | 'percentage' | 'user-list' | 'user-attribute' | 'date-range';
+export type FlagEnvironment = 'development' | 'staging' | 'production' | 'test';
+
+export interface FeatureFlag {
+  /** Unique flag key */
+  key: string;
+  /** Display name */
+  name: string;
+  /** Description */
+  description?: string;
+  /** Status */
+  status: FlagStatus;
+  /** Rollout strategy */
+  strategy: FlagStrategy;
+  /** Strategy configuration */
+  config: FlagConfig;
+  /** Environment */
+  environment?: FlagEnvironment;
+  /** Created by user ID */
+  createdBy?: string;
+  /** Created at timestamp */
+  createdAt: Date;
+  /** Updated at timestamp */
+  updatedAt: Date;
+  /** Tags for organization */
+  tags?: string[];
+}
+
+export interface FlagConfig {
+  /** Boolean value for boolean strategy */
+  value?: boolean;
+  /** Percentage (0-100) for percentage rollout */
+  percentage?: number;
+  /** List of user IDs for user-list strategy */
+  userIds?: string[];
+  /** User attribute rules */
+  userAttributes?: UserAttributeRule[];
+  /** Date range for time-based flags */
+  dateRange?: {
+    start: Date;
+    end: Date;
+  };
+  /** Custom data */
+  customData?: Record<string, unknown>;
+}
+
+export interface UserAttributeRule {
+  /** Attribute key (e.g., 'role', 'country', 'plan') */
+  attribute: string;
+  /** Operator */
+  operator:
+    | 'eq'
+    | 'ne'
+    | 'in'
+    | 'nin'
+    | 'gt'
+    | 'gte'
+    | 'lt'
+    | 'lte'
+    | 'contains'
+    | 'starts-with'
+    | 'ends-with';
+  /** Value to compare */
+  value: string | number | string[] | number[];
+}
+
+export interface FlagEvaluationContext {
+  /** User ID */
+  userId?: string;
+  /** User attributes */
+  userAttributes?: Record<string, string | number | boolean>;
+  /** Environment */
+  environment?: FlagEnvironment;
+  /** Session ID for consistent percentage rollout */
+  sessionId?: string;
+  /** Custom context data */
+  customData?: Record<string, unknown>;
+}
+
+export interface FlagEvaluationResult {
+  /** Flag key */
+  key: string;
+  /** Is flag enabled for this context */
+  enabled: boolean;
+  /** Reason for the decision */
+  reason: string;
+  /** Variant (for A/B testing) */
+  variant?: string;
+  /** Strategy used */
+  strategy: FlagStrategy;
+  /** Evaluation timestamp */
+  evaluatedAt: Date;
+}
+
+export interface FlagVariant {
+  /** Variant key */
+  key: string;
+  /** Display name */
+  name: string;
+  /** Weight for distribution (0-100) */
+  weight: number;
+  /** Variant configuration */
+  config?: Record<string, unknown>;
+}
+
+export interface FlagStats {
+  /** Total evaluations */
+  totalEvaluations: number;
+  /** Enabled evaluations */
+  enabledCount: number;
+  /** Disabled evaluations */
+  disabledCount: number;
+  /** Unique users */
+  uniqueUsers: number;
+  /** Evaluations by variant */
+  variantDistribution?: Record<string, number>;
+  /** Last evaluation */
+  lastEvaluatedAt?: Date;
+}
+
+export interface FlagOverride {
+  /** User ID or session ID */
+  targetId: string;
+  /** Target type */
+  targetType: 'user' | 'session';
+  /** Override value */
+  enabled: boolean;
+  /** Expiration date */
+  expiresAt?: Date;
+  /** Created at */
+  createdAt: Date;
+}
+
+export interface FlagEvent {
+  /** Event type */
+  type: 'created' | 'updated' | 'deleted' | 'evaluated' | 'override-set' | 'override-removed';
+  /** Flag key */
+  flagKey: string;
+  /** User ID */
+  userId?: string;
+  /** Event data */
+  data?: Record<string, unknown>;
+  /** Timestamp */
+  timestamp: Date;
+}
+
+export interface FeatureFlagConfig {
+  /** Default environment */
+  defaultEnvironment?: FlagEnvironment;
+  /** Enable analytics */
+  analytics?: boolean;
+  /** Cache TTL in seconds */
+  cacheTtl?: number;
+  /** Redis URL for distributed caching */
+  redisUrl?: string;
+}
+
+export interface FlagListFilters {
+  /** Filter by status */
+  status?: FlagStatus;
+  /** Filter by environment */
+  environment?: FlagEnvironment;
+  /** Filter by tags */
+  tags?: string[];
+  /** Search by name or description */
+  search?: string;
+}
+
+export interface ABTestConfig {
+  /** Flag key */
+  flagKey: string;
+  /** Variants */
+  variants: FlagVariant[];
+  /** Traffic allocation percentage */
+  trafficAllocation: number;
+  /** Conversion goal event */
+  conversionGoal?: string;
+}
+
+export interface ABTestResult {
+  /** Variant key */
+  variant: string;
+  /** Impressions */
+  impressions: number;
+  /** Conversions */
+  conversions: number;
+  /** Conversion rate */
+  conversionRate: number;
+  /** Statistical significance */
+  isSignificant: boolean;
+}

package/src/modules/i18n/i18n.middleware.ts

@@ -0,0 +1,186 @@
+import type { Request, Response, NextFunction } from 'express';
+import type { I18nService } from './i18n.service.js';
+import type { I18nMiddlewareOptions, LocaleDetectionResult, Locale } from './types.js';
+
+/**
+ * Request with i18n properties
+ */
+export interface I18nRequest extends Request {
+  locale?: Locale;
+  t?: (key: string, options?: Record<string, unknown>) => string;
+  localeDetection?: LocaleDetectionResult;
+}
+
+/**
+ * Create i18n middleware
+ */
+export function createI18nMiddleware(
+  i18nService: I18nService,
+  options: I18nMiddlewareOptions = {}
+): (req: Request, res: Response, next: NextFunction) => void {
+  const {
+    queryParam = 'lang',
+    cookieName = 'locale',
+    headerName = 'Accept-Language',
+    detectFromHeader = true,
+  } = options;
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const i18nReq = req as I18nRequest;
+
+    // Detect locale
+    const detection = detectLocale(req, i18nService, {
+      queryParam,
+      cookieName,
+      headerName,
+      detectFromHeader,
+    });
+
+    i18nReq.locale = detection.locale;
+    i18nReq.localeDetection = detection;
+
+    // Add translation function to request
+    i18nReq.t = (key: string, options?: Record<string, unknown>) => {
+      return i18nService.t(key, {
+        ...options,
+        locale: i18nReq.locale,
+      });
+    };
+
+    // Set Content-Language header
+    res.setHeader('Content-Language', detection.locale);
+
+    next();
+  };
+}
+
+/**
+ * Detect locale from request
+ */
+export function detectLocale(
+  req: Request,
+  i18nService: I18nService,
+  options: I18nMiddlewareOptions = {}
+): LocaleDetectionResult {
+  const {
+    queryParam = 'lang',
+    cookieName = 'locale',
+    headerName = 'Accept-Language',
+    detectFromHeader = true,
+  } = options;
+
+  // 1. Check query parameter
+  if (queryParam && req.query[queryParam]) {
+    const locale = req.query[queryParam] as string;
+    if (i18nService.isLocaleSupported(locale)) {
+      return {
+        locale,
+        source: 'query',
+        confidence: 1.0,
+      };
+    }
+  }
+
+  // 2. Check cookie
+  if (cookieName && req.cookies && req.cookies[cookieName]) {
+    const locale = req.cookies[cookieName] as string;
+    if (i18nService.isLocaleSupported(locale)) {
+      return {
+        locale,
+        source: 'cookie',
+        confidence: 0.9,
+      };
+    }
+  }
+
+  // 3. Check Accept-Language header
+  if (detectFromHeader && headerName) {
+    const acceptLanguage = req.headers[headerName.toLowerCase()] as string | undefined;
+    if (acceptLanguage) {
+      const detectedLocale = parseAcceptLanguage(acceptLanguage, i18nService);
+      if (detectedLocale) {
+        return {
+          locale: detectedLocale.locale,
+          source: 'header',
+          confidence: detectedLocale.quality,
+        };
+      }
+    }
+  }
+
+  // 4. Use default locale
+  const defaultLocale = i18nService.getSupportedLocales()[0] || 'en';
+  return {
+    locale: defaultLocale,
+    source: 'default',
+    confidence: 0.5,
+  };
+}
+
+/**
+ * Parse Accept-Language header
+ */
+function parseAcceptLanguage(
+  header: string,
+  i18nService: I18nService
+): { locale: Locale; quality: number } | null {
+  const languages = header
+    .split(',')
+    .map((lang) => {
+      const parts = lang.trim().split(';');
+      const localePart = parts[0]?.split('-')[0];
+      const locale = localePart || 'en'; // Get base language (e.g., 'en' from 'en-US')
+      const qMatch = parts[1]?.match(/q=([\d.]+)/);
+      const quality = qMatch?.[1] ? parseFloat(qMatch[1]) : 1.0;
+
+      return { locale, quality };
+    })
+    .sort((a, b) => b.quality - a.quality);
+
+  // Find first supported locale
+  for (const lang of languages) {
+    if (i18nService.isLocaleSupported(lang.locale)) {
+      return { locale: lang.locale, quality: lang.quality };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Locale switcher middleware
+ */
+export function localeSwitcher(
+  i18nService: I18nService,
+  cookieName = 'locale'
+): (req: Request, res: Response) => void {
+  return (req: Request, res: Response): void => {
+    const { locale } = req.body as { locale?: string };
+
+    if (!locale) {
+      res.status(400).json({ error: 'Locale is required' });
+      return;
+    }
+
+    if (!i18nService.isLocaleSupported(locale)) {
+      res.status(400).json({
+        error: 'Unsupported locale',
+        supportedLocales: i18nService.getSupportedLocales(),
+      });
+      return;
+    }
+
+    // Set cookie
+    res.cookie(cookieName, locale, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      maxAge: 365 * 24 * 60 * 60 * 1000, // 1 year
+      sameSite: 'lax',
+    });
+
+    res.json({
+      success: true,
+      locale,
+    });
+  };
+}

package/src/modules/i18n/i18n.routes.ts

@@ -0,0 +1,191 @@
+import { Router } from 'express';
+import type { Request, Response } from 'express';
+import type { I18nService } from './i18n.service.js';
+import { localeSwitcher } from './i18n.middleware.js';
+import type { I18nRequest } from './i18n.middleware.js';
+
+/**
+ * Create i18n routes
+ */
+export function createI18nRoutes(i18nService: I18nService): Router {
+  const router = Router();
+
+  /**
+   * Get supported locales
+   * GET /locales
+   */
+  router.get('/locales', (_req: Request, res: Response) => {
+    const locales = i18nService.getSupportedLocales().map((locale) => {
+      const info = i18nService.getLocaleInfo(locale);
+      return {
+        code: locale,
+        name: info?.name || locale,
+        englishName: info?.englishName,
+        direction: info?.direction || 'ltr',
+      };
+    });
+
+    res.json({ locales });
+  });
+
+  /**
+   * Get current locale
+   * GET /locale
+   */
+  router.get('/locale', (req: Request, res: Response) => {
+    const i18nReq = req as I18nRequest;
+
+    res.json({
+      locale: i18nReq.locale,
+      detection: i18nReq.localeDetection,
+      info: i18nService.getLocaleInfo(i18nReq.locale || ''),
+    });
+  });
+
+  /**
+   * Switch locale
+   * POST /locale
+   * Body: { locale: 'en' }
+   */
+  router.post('/locale', localeSwitcher(i18nService));
+
+  /**
+   * Get translations for a namespace
+   * GET /translations/:namespace?locale=en
+   */
+  router.get('/translations/:namespace', (req: Request, res: Response) => {
+    const { namespace } = req.params;
+    const locale = (req.query.locale as string) || (req as I18nRequest).locale || 'en';
+
+    if (!i18nService.isLocaleSupported(locale)) {
+      res.status(400).json({ error: 'Unsupported locale' });
+      return;
+    }
+
+    const translations = i18nService.exportTranslations(locale, namespace);
+
+    if (!translations) {
+      res.status(404).json({ error: 'Translations not found' });
+      return;
+    }
+
+    res.json({
+      locale,
+      namespace,
+      translations,
+    });
+  });
+
+  /**
+   * Get translation metadata
+   * GET /translations/:namespace/metadata?locale=en
+   */
+  router.get('/translations/:namespace/metadata', async (req: Request, res: Response) => {
+    const { namespace } = req.params;
+    const locale = (req.query.locale as string) || (req as I18nRequest).locale || 'en';
+
+    if (!i18nService.isLocaleSupported(locale)) {
+      res.status(400).json({ error: 'Unsupported locale' });
+      return;
+    }
+
+    const metadata = await i18nService.getTranslationMetadata(locale, namespace);
+
+    res.json({
+      locale,
+      namespace,
+      metadata,
+    });
+  });
+
+  /**
+   * Get missing translations
+   * GET /translations/:namespace/missing?base=en&target=fr
+   */
+  router.get('/translations/:namespace/missing', (req: Request, res: Response) => {
+    const { namespace } = req.params;
+    const { base, target } = req.query;
+
+    if (!base || !target) {
+      res.status(400).json({ error: 'Base and target locales are required' });
+      return;
+    }
+
+    if (!i18nService.isLocaleSupported(base as string)) {
+      res.status(400).json({ error: 'Unsupported base locale' });
+      return;
+    }
+
+    if (!i18nService.isLocaleSupported(target as string)) {
+      res.status(400).json({ error: 'Unsupported target locale' });
+      return;
+    }
+
+    const missing = i18nService.getMissingTranslations(base as string, target as string, namespace);
+
+    res.json({
+      base,
+      target,
+      namespace,
+      missingKeys: missing,
+      count: missing.length,
+    });
+  });
+
+  /**
+   * Translate a key
+   * POST /translate
+   * Body: { key: 'welcome.message', locale: 'en', variables: { name: 'John' } }
+   */
+  router.post('/translate', (req: Request, res: Response) => {
+    const { key, locale, variables, namespace, defaultValue, count } = req.body as {
+      key: string;
+      locale?: string;
+      variables?: Record<string, string | number>;
+      namespace?: string;
+      defaultValue?: string;
+      count?: number;
+    };
+
+    if (!key) {
+      res.status(400).json({ error: 'Translation key is required' });
+      return;
+    }
+
+    const targetLocale = locale || (req as I18nRequest).locale || 'en';
+
+    if (!i18nService.isLocaleSupported(targetLocale)) {
+      res.status(400).json({ error: 'Unsupported locale' });
+      return;
+    }
+
+    const translation = i18nService.t(key, {
+      locale: targetLocale,
+      namespace,
+      variables,
+      defaultValue,
+      count,
+    });
+
+    res.json({
+      key,
+      locale: targetLocale,
+      translation,
+    });
+  });
+
+  /**
+   * Clear translation cache
+   * POST /cache/clear
+   */
+  router.post('/cache/clear', (_req: Request, res: Response) => {
+    i18nService.clearCache();
+
+    res.json({
+      success: true,
+      message: 'Translation cache cleared',
+    });
+  });
+
+  return router;
+}