@zintrust/core 0.1.1 → 0.1.3

package/src/templates/project/basic/config/logging/SlackLogger.ts.tpl

@@ -0,0 +1,156 @@
+/**
+ * Slack Notification Logger
+ * Sends warn/error/fatal log events to a Slack incoming webhook.
+ *
+ * Enabled via env:
+ *  - SLACK_LOG_ENABLED (default: false)
+ *  - SLACK_LOG_WEBHOOK_URL
+ *  - SLACK_LOG_LEVELS (comma-separated; default: "warn,error,fatal")
+ *  - SLACK_LOG_BATCH_WINDOW_MS (default: 5000)
+ */
+
+import { Env } from '@config/env';
+import { ErrorFactory } from '@exceptions/ZintrustError';
+import { HttpClient } from '@httpClient/Http';
+
+export type SlackLogEvent = {
+  timestamp: string;
+  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  message: string;
+  category?: string;
+  data?: unknown;
+  error?: string;
+};
+
+type SlackPayload = {
+  text?: string;
+  attachments?: Array<{ color?: string; text: string }>;
+};
+
+const isEnabled = (): boolean => Env.getBool('SLACK_LOG_ENABLED', false);
+
+const getLevels = (): Set<string> => {
+  const raw = Env.get('SLACK_LOG_LEVELS', 'warn,error,fatal');
+  return new Set(
+    raw
+      .split(',')
+      .map((s) => s.trim().toLowerCase())
+      .filter((s) => s.length > 0)
+  );
+};
+
+const levelToColor = (level: SlackLogEvent['level']): string => {
+  if (level === 'fatal' || level === 'error') return '#D50200';
+  if (level === 'warn') return '#D39E00';
+  return '#439FE0';
+};
+
+const formatEventText = (ev: SlackLogEvent): string => {
+  const header = `*${ev.level.toUpperCase()}* ${ev.message}`;
+  const metaParts: string[] = [];
+  if (ev.category !== undefined) metaParts.push(`category=${ev.category}`);
+  metaParts.push(`ts=${ev.timestamp}`);
+
+  const meta = metaParts.length > 0 ? `\n_${metaParts.join(' ')}_` : '';
+
+  const err = ev.error === undefined ? '' : `\n*error:* ${String(ev.error)}`;
+  const data = ev.data === undefined ? '' : `\n*data:* \`${JSON.stringify(ev.data)}\``;
+
+  return `${header}${meta}${err}${data}`;
+};
+
+let buffer: SlackLogEvent[] = [];
+let flushPromise: Promise<void> | undefined;
+let dedupeKeys = new Set<string>();
+
+const dedupeKeyFor = (ev: SlackLogEvent): string => {
+  const base = `${ev.level}:${ev.message}:${ev.error ?? ''}`;
+  return base.length > 500 ? base.slice(0, 500) : base;
+};
+
+const sendBatch = async (events: SlackLogEvent[]): Promise<void> => {
+  const webhookUrl = Env.get('SLACK_LOG_WEBHOOK_URL').trim();
+  if (webhookUrl.length === 0) {
+    throw ErrorFactory.createConfigError(
+      'SLACK_LOG_WEBHOOK_URL is required when Slack logging is enabled'
+    );
+  }
+
+  const lines = events.map((e) => formatEventText(e)).join('\n\n');
+
+  const payload: SlackPayload = {
+    attachments: [
+      {
+        color: levelToColor(events[0]?.level ?? 'warn'),
+        text: lines,
+      },
+    ],
+  };
+
+  await HttpClient.post(webhookUrl, payload).send();
+};
+
+const flushNow = async (): Promise<void> => {
+  const toSend = buffer;
+  buffer = [];
+  dedupeKeys = new Set<string>();
+
+  if (!isEnabled()) return;
+  if (toSend.length === 0) return;
+
+  try {
+    await sendBatch(toSend);
+  } catch {
+    // Best-effort: never throw from logging.
+  }
+};
+
+const scheduleFlush = async (): Promise<void> => {
+  if (flushPromise !== undefined) return flushPromise;
+
+  const windowMs = Math.max(0, Env.getInt('SLACK_LOG_BATCH_WINDOW_MS', 5000));
+
+  const promise = new Promise<void>((resolve) => {
+    const run = async (): Promise<void> => {
+      try {
+        await flushNow();
+      } finally {
+        resolve(undefined);
+      }
+    };
+
+    if (windowMs === 0 || typeof globalThis.setTimeout !== 'function') {
+      void run();
+      return;
+    }
+
+    globalThis.setTimeout(() => {
+      void run();
+    }, windowMs);
+  });
+
+  flushPromise = promise.finally(() => {
+    flushPromise = undefined;
+  });
+
+  return flushPromise;
+};
+
+export const SlackLogger = Object.freeze({
+  async enqueue(event: SlackLogEvent): Promise<void> {
+    if (!isEnabled()) return Promise.resolve();
+
+    const levels = getLevels();
+    if (!levels.has(event.level)) return Promise.resolve();
+
+    const key = dedupeKeyFor(event);
+    if (dedupeKeys.has(key)) return scheduleFlush();
+
+    dedupeKeys.add(key);
+    buffer.push(event);
+
+    return scheduleFlush();
+  },
+});
+
+export default SlackLogger;

package/src/templates/project/basic/config/mail.ts.tpl

@@ -0,0 +1,141 @@
+/**
+ * Mail Configuration
+ * Runtime mail drivers and settings
+ * Sealed namespace for immutability
+ */
+
+import { Env } from '@config/env';
+
+export type MailDriverName = 'disabled' | 'sendgrid' | 'smtp' | 'ses' | 'mailgun';
+
+export type DisabledMailDriverConfig = {
+  driver: 'disabled';
+};
+
+export type SendGridMailDriverConfig = {
+  driver: 'sendgrid';
+  apiKey: string;
+};
+
+export type MailgunMailDriverConfig = {
+  driver: 'mailgun';
+  apiKey: string;
+  domain: string;
+  baseUrl: string;
+};
+
+// Placeholders for future drivers (kept config-first)
+export type SmtpMailDriverConfig = {
+  driver: 'smtp';
+  host: string;
+  port: number;
+  username: string;
+  password: string;
+  secure: boolean | 'starttls';
+};
+
+export type SesMailDriverConfig = {
+  driver: 'ses';
+  region: string;
+};
+
+export type MailDriverConfig =
+  | DisabledMailDriverConfig
+  | SendGridMailDriverConfig
+  | MailgunMailDriverConfig
+  | SmtpMailDriverConfig
+  | SesMailDriverConfig;
+
+type MailDrivers = {
+  disabled: DisabledMailDriverConfig;
+  sendgrid: SendGridMailDriverConfig;
+  mailgun: MailgunMailDriverConfig;
+  smtp: SmtpMailDriverConfig;
+  ses: SesMailDriverConfig;
+};
+
+type MailConfigInput = {
+  default: MailDriverName;
+  from: {
+    address: string;
+    name: string;
+  };
+  drivers: MailDrivers;
+};
+
+const getMailDriver = (config: MailConfigInput): MailDriverConfig => {
+  const defaultDriver = config.default;
+
+  if (Object.hasOwn(config.drivers, defaultDriver)) {
+    const driverName = defaultDriver as keyof MailDrivers;
+    return config.drivers[driverName];
+  }
+
+  return config.drivers.disabled;
+};
+
+const mailConfigObj = {
+  /**
+   * Default mail driver
+   */
+  default: (Env.get('MAIL_DRIVER', 'disabled') as MailDriverName) ?? 'disabled',
+
+  /**
+   * Default "From" identity
+   */
+  from: {
+    address: Env.get('MAIL_FROM_ADDRESS', ''),
+    name: Env.get('MAIL_FROM_NAME', ''),
+  },
+
+  /**
+   * Driver configs
+   */
+  drivers: {
+    disabled: {
+      driver: 'disabled' as const,
+    },
+
+    sendgrid: {
+      driver: 'sendgrid' as const,
+      apiKey: Env.get('SENDGRID_API_KEY', ''),
+    },
+
+    mailgun: {
+      driver: 'mailgun' as const,
+      apiKey: Env.get('MAILGUN_API_KEY', ''),
+      domain: Env.get('MAILGUN_DOMAIN', ''),
+      baseUrl: Env.get('MAILGUN_BASE_URL', 'https://api.mailgun.net').trim(),
+    },
+
+    smtp: {
+      driver: 'smtp' as const,
+      host: Env.get('MAIL_HOST', ''),
+      port: Env.getInt('MAIL_PORT', 587),
+      username: Env.get('MAIL_USERNAME', ''),
+      password: Env.get('MAIL_PASSWORD', ''),
+      secure: (() => {
+        const raw = Env.get('MAIL_SECURE', '').trim().toLowerCase();
+        if (raw === 'starttls') return 'starttls' as const;
+        if (raw === 'tls' || raw === 'ssl' || raw === 'smtps' || raw === 'implicit') return true;
+        if (raw === 'none' || raw === 'off' || raw === 'false' || raw === '0') return false;
+        return Env.getBool('MAIL_SECURE', false);
+      })(),
+    },
+
+    ses: {
+      driver: 'ses' as const,
+      region: Env.get('AWS_REGION', 'us-east-1'),
+    },
+  },
+
+  /**
+   * Get selected driver config
+   */
+  getDriver(): MailDriverConfig {
+    return getMailDriver(this);
+  },
+} as const;
+
+export const mailConfig = Object.freeze(mailConfigObj);
+export type MailConfig = typeof mailConfig;

package/src/templates/project/basic/config/middleware.ts.tpl

@@ -0,0 +1,27 @@
+import { CsrfMiddleware } from '@middleware/CsrfMiddleware';
+import { ErrorHandlerMiddleware } from '@middleware/ErrorHandlerMiddleware';
+import { LoggingMiddleware } from '@middleware/LoggingMiddleware';
+import type { Middleware } from '@middleware/MiddlewareStack';
+import { RateLimiter } from '@middleware/RateLimiter';
+import { SecurityMiddleware } from '@middleware/SecurityMiddleware';
+
+export type MiddlewareConfig = {
+  global: Middleware[];
+  route: Record<string, Middleware>;
+};
+
+const shared = Object.freeze({
+  log: LoggingMiddleware.create(),
+  error: ErrorHandlerMiddleware.create(),
+  security: SecurityMiddleware.create(),
+  rateLimit: RateLimiter.create(),
+  csrf: CsrfMiddleware.create(),
+} satisfies Record<string, Middleware>);
+
+const middlewareConfigObj: MiddlewareConfig = {
+  global: [shared.log, shared.error, shared.security, shared.rateLimit, shared.csrf],
+  route: shared,
+};
+
+export const middlewareConfig = Object.freeze(middlewareConfigObj);
+export default middlewareConfig;

package/src/templates/project/basic/config/notification.ts.tpl

@@ -0,0 +1,86 @@
+/**
+ * Notification Configuration
+ *
+ * Config-first mapping of notification providers.
+ * Keeps runtime driver selection in one place and uses Env for safe access.
+ */
+
+import { Env } from '@config/env';
+
+export type KnownNotificationDriverName = 'console' | 'termii' | 'twilio' | 'slack';
+
+export type ConsoleNotificationDriverConfig = { driver: 'console' };
+
+export type TermiiNotificationDriverConfig = {
+  driver: 'termii';
+  apiKey: string;
+  sender: string;
+  endpoint: string;
+};
+
+export type TwilioNotificationDriverConfig = {
+  driver: 'twilio';
+  accountSid: string;
+  authToken: string;
+  fromNumber: string;
+};
+
+export type SlackNotificationDriverConfig = {
+  driver: 'slack';
+  webhookUrl: string;
+};
+
+export type KnownNotificationDriverConfig =
+  | ConsoleNotificationDriverConfig
+  | TermiiNotificationDriverConfig
+  | TwilioNotificationDriverConfig
+  | SlackNotificationDriverConfig;
+
+type NotificationProviders = {
+  console: ConsoleNotificationDriverConfig;
+  termii: TermiiNotificationDriverConfig;
+  twilio: TwilioNotificationDriverConfig;
+  slack: SlackNotificationDriverConfig;
+};
+
+const notificationConfigObj = {
+  /**
+   * Normalized notification driver name.
+   *
+   * NOTE: This intentionally supports custom driver names (e.g. project-specific drivers),
+   * so it returns a string rather than a strict union.
+   */
+  getDriverName(): string {
+    return Env.get('NOTIFICATION_DRIVER', 'console').trim().toLowerCase();
+  },
+
+  /**
+   * Provider configs.
+   */
+  providers: {
+    console: {
+      driver: 'console' as const,
+    },
+
+    termii: {
+      driver: 'termii' as const,
+      apiKey: Env.get('TERMII_API_KEY', ''),
+      sender: Env.get('TERMII_SENDER', 'Zintrust'),
+      endpoint: Env.get('TERMII_ENDPOINT', 'https://api.termii.com/sms/send'),
+    },
+
+    twilio: {
+      driver: 'twilio' as const,
+      accountSid: Env.get('TWILIO_ACCOUNT_SID', ''),
+      authToken: Env.get('TWILIO_AUTH_TOKEN', ''),
+      fromNumber: Env.get('TWILIO_FROM_NUMBER', ''),
+    },
+
+    slack: {
+      driver: 'slack' as const,
+      webhookUrl: Env.get('SLACK_WEBHOOK_URL', ''),
+    },
+  } satisfies NotificationProviders,
+} as const;
+
+export default Object.freeze(notificationConfigObj);

package/src/templates/project/basic/config/security.ts.tpl

@@ -4,9 +4,10 @@
  * Sealed namespace for immutability
  */
 
+import { appConfig } from '@config/app';
 import { Env } from '@config/env';
 import { Logger } from '@config/logger';
-import { ErrorFactory } from '@zintrust/core';
+import { ErrorFactory } from '@exceptions/ZintrustError';
 
 /**
  * Helper to warn about missing secrets
@@ -14,9 +15,7 @@ import { ErrorFactory } from '@zintrust/core';
 function warnMissingSecret(secretName: string): string {
   Logger.error(`❌ CRITICAL: ${secretName} environment variable is not set!`);
   Logger.error('⚠️  Application may not function correctly. Set this in production immediately.');
-
-  const nodeEnv = Env.get('NODE_ENV', 'development');
-  if (nodeEnv === 'production') {
+  if (appConfig.isProduction()) {
     throw ErrorFactory.createConfigError(`Missing required secret: ${secretName}`, { secretName });
   }
 
@@ -44,7 +43,7 @@ const securityConfigObj = {
     algorithm: Env.get('JWT_ALGORITHM', 'HS256') as 'HS256' | 'HS512' | 'RS256',
     expiresIn: Env.get('JWT_EXPIRES_IN', '1h'),
     refreshExpiresIn: Env.get('JWT_REFRESH_EXPIRES_IN', '7d'),
-    issuer: Env.get('JWT_ISSUER', '@zintrust/core'),
+    issuer: Env.get('JWT_ISSUER', 'zintrust'),
     audience: Env.get('JWT_AUDIENCE', 'zintrust-api'),
   },
 

package/src/templates/project/basic/config/startup.ts.tpl

@@ -0,0 +1,27 @@
+/**
+ * Startup Configuration
+ *
+ * Startup-only controls (evaluated during Application.boot()).
+ */
+
+import { Env } from '@config/env';
+
+export type StartupConfig = {
+  healthChecksEnabled: boolean;
+  validateSecrets: boolean;
+  checkDatabase: boolean;
+  checkCache: boolean;
+  timeoutMs: number;
+  continueOnFailure: boolean;
+};
+
+export const startupConfig = Object.freeze({
+  healthChecksEnabled: Env.getBool('STARTUP_HEALTH_CHECKS', true),
+  validateSecrets: Env.getBool('STARTUP_VALIDATE_SECRETS', true),
+  checkDatabase: Env.getBool('STARTUP_CHECK_DB', false),
+  checkCache: Env.getBool('STARTUP_CHECK_CACHE', false),
+  timeoutMs: Env.getInt('STARTUP_HEALTH_TIMEOUT_MS', 2500),
+  continueOnFailure: Env.getBool('STARTUP_CONTINUE_ON_FAILURE', false),
+} satisfies StartupConfig);
+
+export default startupConfig;

package/src/templates/project/basic/config/storage.ts.tpl

@@ -18,8 +18,8 @@ type LocalStorageDriverConfig = {
 
 type S3StorageDriverConfig = {
   driver: 's3';
-  key: EnvGetValue;
-  secret: EnvGetValue;
+  accessKeyId: EnvGetValue;
+  secretAccessKey: EnvGetValue;
   region: typeof Env.AWS_REGION;
   bucket: EnvGetValue;
   url: EnvGetValue;
@@ -27,6 +27,16 @@ type S3StorageDriverConfig = {
   usePathStyleUrl: EnvGetBoolValue;
 };
 
+type R2StorageDriverConfig = {
+  driver: 'r2';
+  accessKeyId: EnvGetValue;
+  secretAccessKey: EnvGetValue;
+  region: EnvGetValue;
+  bucket: EnvGetValue;
+  endpoint: EnvGetValue;
+  url: EnvGetValue;
+};
+
 type GcsStorageDriverConfig = {
   driver: 'gcs';
   projectId: EnvGetValue;
@@ -38,6 +48,7 @@ type GcsStorageDriverConfig = {
 type StorageDrivers = {
   local: LocalStorageDriverConfig;
   s3: S3StorageDriverConfig;
+  r2: R2StorageDriverConfig;
   gcs: GcsStorageDriverConfig;
 };
 
@@ -45,11 +56,14 @@ type StorageDriverName = keyof StorageDrivers;
 type StorageDriverConfig = StorageDrivers[StorageDriverName];
 
 type StorageConfigRuntime = {
-  default: string;
-  drivers: StorageDrivers;
+  readonly default: string;
+  readonly drivers: StorageDrivers;
 };
 
-const isStorageDriverName = (value: string, drivers: StorageDrivers): value is StorageDriverName => {
+const isStorageDriverName = (
+  value: string,
+  drivers: StorageDrivers
+): value is StorageDriverName => {
   return value in drivers;
 };
 
@@ -63,39 +77,54 @@ const getStorageDriver = (config: StorageConfigRuntime): StorageDriverConfig =>
   return config.drivers.local;
 };
 
+const getDrivers = (): StorageDrivers => ({
+  local: {
+    driver: 'local' as const,
+    root: Env.get('STORAGE_PATH', 'storage'),
+    url: Env.get('STORAGE_URL', '/storage'),
+    visibility: Env.get('STORAGE_VISIBILITY', 'private'),
+  },
+  s3: {
+    driver: 's3' as const,
+    accessKeyId: Env.get('AWS_ACCESS_KEY_ID', ''),
+    secretAccessKey: Env.get('AWS_SECRET_ACCESS_KEY', ''),
+    region: Env.AWS_REGION,
+    bucket: Env.get('AWS_S3_BUCKET', ''),
+    url: Env.get('AWS_S3_URL', ''),
+    endpoint: Env.get('AWS_S3_ENDPOINT', ''),
+    usePathStyleUrl: Env.getBool('AWS_S3_USE_PATH_STYLE_URL', false),
+  },
+  r2: {
+    driver: 'r2' as const,
+    accessKeyId: Env.get('R2_ACCESS_KEY_ID', ''),
+    secretAccessKey: Env.get('R2_SECRET_ACCESS_KEY', ''),
+    region: Env.get('R2_REGION', ''),
+    bucket: Env.get('R2_BUCKET', ''),
+    endpoint: Env.get('R2_ENDPOINT', ''),
+    url: Env.get('R2_URL', ''),
+  },
+  gcs: {
+    driver: 'gcs' as const,
+    projectId: Env.get('GCS_PROJECT_ID', ''),
+    keyFile: Env.get('GCS_KEY_FILE', ''),
+    bucket: Env.get('GCS_BUCKET', ''),
+    url: Env.get('GCS_URL', ''),
+  },
+});
+
 const storageConfigObj = {
   /**
-   * Default storage driver
+   * Default storage driver (dynamic; tests may mutate process.env)
    */
-  default: Env.get('STORAGE_DRIVER', 'local'),
+  get default(): string {
+    return Env.get('STORAGE_DRIVER', 'local');
+  },
 
   /**
-   * Storage drivers configuration
+   * Storage drivers configuration (dynamic; tests may mutate process.env)
    */
-  drivers: {
-    local: {
-      driver: 'local' as const,
-      root: Env.get('STORAGE_PATH', 'storage'),
-      url: Env.get('STORAGE_URL', '/storage'),
-      visibility: Env.get('STORAGE_VISIBILITY', 'private'),
-    },
-    s3: {
-      driver: 's3' as const,
-      key: Env.get('AWS_ACCESS_KEY_ID'),
-      secret: Env.get('AWS_SECRET_ACCESS_KEY'),
-      region: Env.AWS_REGION,
-      bucket: Env.get('AWS_S3_BUCKET'),
-      url: Env.get('AWS_S3_URL'),
-      endpoint: Env.get('AWS_S3_ENDPOINT'),
-      usePathStyleUrl: Env.getBool('AWS_S3_USE_PATH_STYLE_URL', false),
-    },
-    gcs: {
-      driver: 'gcs' as const,
-      projectId: Env.get('GCS_PROJECT_ID'),
-      keyFile: Env.get('GCS_KEY_FILE'),
-      bucket: Env.get('GCS_BUCKET'),
-      url: Env.get('GCS_URL'),
-    },
+  get drivers(): StorageDrivers {
+    return getDrivers();
   },
 
   /**
@@ -108,26 +137,32 @@ const storageConfigObj = {
   /**
    * Temporary file settings
    */
-  temp: {
-    path: Env.get('TEMP_PATH', 'storage/temp'),
-    maxAge: Env.getInt('TEMP_FILE_MAX_AGE', 86400), // 24 hours
+  get temp(): { path: string; maxAge: number } {
+    return {
+      path: Env.get('TEMP_PATH', 'storage/temp'),
+      maxAge: Env.getInt('TEMP_FILE_MAX_AGE', 86400), // 24 hours
+    };
   },
 
   /**
    * Uploads settings
    */
-  uploads: {
-    maxSize: Env.get('MAX_UPLOAD_SIZE', '100mb'),
-    allowedMimes: Env.get('ALLOWED_UPLOAD_MIMES', 'jpg,jpeg,png,pdf,doc,docx'),
-    path: Env.get('UPLOADS_PATH', 'storage/uploads'),
+  get uploads(): { maxSize: string; allowedMimes: string; path: string } {
+    return {
+      maxSize: Env.get('MAX_UPLOAD_SIZE', '100mb'),
+      allowedMimes: Env.get('ALLOWED_UPLOAD_MIMES', 'jpg,jpeg,png,pdf,doc,docx'),
+      path: Env.get('UPLOADS_PATH', 'storage/uploads'),
+    };
   },
 
   /**
    * Backups settings
    */
-  backups: {
-    path: Env.get('BACKUPS_PATH', 'storage/backups'),
-    driver: Env.get('BACKUP_DRIVER', 's3'),
+  get backups(): { path: string; driver: string } {
+    return {
+      path: Env.get('BACKUPS_PATH', 'storage/backups'),
+      driver: Env.get('BACKUP_DRIVER', 's3'),
+    };
   },
 };
 

package/src/templates/project/basic/database/migrations/index.ts.tpl

@@ -1,2 +1,2 @@
 // Placeholder for migrations
-export {};
+export const migrations = Object.freeze([] as const);

package/src/templates/project/basic/package.json.tpl

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@zintrust/core": "^0.1.0"
+    "@zintrust/core": "^0.1.1"
   },
   "devDependencies": {
     "tsx": "^4.21.0",