@zintrust/core 0.1.20 → 0.1.21

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

@@ -1,121 +1,14 @@
 /**
- * HTTP Endpoint Logger
- * Sends logs to an external HTTP logging service.
+ * HTTP Logger (starter override)
  *
- * Enabled via env:
- *  - HTTP_LOG_ENABLED (default: false)
- *  - HTTP_LOG_ENDPOINT_URL
- *  - HTTP_LOG_BATCH_SIZE (default: 50)
- *  - HTTP_LOG_AUTH_TOKEN (optional)
+ * Starter projects should import the framework's HttpLogger from `@zintrust/core`.
+ * This keeps templates free of deep/internal imports.
  */
 
-import { delay } from '@zintrust/core';
-import { Env } from '@zintrust/core';
-import { ErrorFactory } from '@zintrust/core';
-import { HttpClient } from '@zintrust/core';
+import { HttpLogger } from '@zintrust/core';
+import type { HttpLogEvent } from '@zintrust/core';
 
-export type HttpLogEvent = {
-  timestamp: string;
-  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-  message: string;
-  category?: string;
-  data?: unknown;
-  error?: string;
-};
-
-const isEnabled = (): boolean => Env.getBool('HTTP_LOG_ENABLED', false);
-
-let buffer: HttpLogEvent[] = [];
-let flushPromise: Promise<void> | undefined;
-
-const postBatch = async (events: HttpLogEvent[]): Promise<void> => {
-  const endpoint = Env.get('HTTP_LOG_ENDPOINT_URL').trim();
-  if (endpoint.length === 0) {
-    throw ErrorFactory.createConfigError(
-      'HTTP_LOG_ENDPOINT_URL is required when HTTP logging is enabled'
-    );
-  }
-
-  const token = Env.get('HTTP_LOG_AUTH_TOKEN').trim();
-
-  const builder = HttpClient.post(endpoint, {
-    sentAt: new Date().toISOString(),
-    count: events.length,
-    events,
-  });
-
-  if (token.length > 0) {
-    builder.withAuth(token, 'Bearer');
-  }
-
-  await builder.send();
-};
-
-const flushNow = async (): Promise<void> => {
-  const toSend = buffer;
-  buffer = [];
-
-  if (!isEnabled()) return;
-  if (toSend.length === 0) return;
-
-  const maxRetries = 3;
-
-  const attemptPost = async (attempt: number): Promise<void> => {
-    try {
-      await postBatch(toSend);
-    } catch {
-      if (attempt >= maxRetries) return;
-      const backoffMs = 100 * 2 ** attempt;
-      await delay(backoffMs);
-      await attemptPost(attempt + 1);
-    }
-  };
-
-  await attemptPost(0);
-};
-
-const scheduleFlush = async (): Promise<void> => {
-  if (flushPromise !== undefined) return flushPromise;
-
-  const promise = new Promise<void>((resolve) => {
-    const run = async (): Promise<void> => {
-      try {
-        await flushNow();
-      } finally {
-        resolve(undefined);
-      }
-    };
-
-    if (typeof globalThis.setTimeout !== 'function') {
-      void run();
-      return;
-    }
-
-    globalThis.setTimeout(() => {
-      void run();
-    }, 0);
-  });
-
-  flushPromise = promise.finally(() => {
-    flushPromise = undefined;
-  });
-
-  return flushPromise;
-};
-
-export const HttpLogger = Object.freeze({
-  async enqueue(event: HttpLogEvent): Promise<void> {
-    if (!isEnabled()) return Promise.resolve(); // NOSONAR
-
-    buffer.push(event);
-
-    const batchSize = Math.max(1, Env.getInt('HTTP_LOG_BATCH_SIZE', 50));
-    if (buffer.length >= batchSize) {
-      return scheduleFlush();
-    }
-
-    return scheduleFlush();
-  },
-});
+export { HttpLogger };
+export type { HttpLogEvent };
 
 export default HttpLogger;

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

@@ -1,23 +1,69 @@
+import { Env, type MailConfigOverrides } from '@zintrust/core';
+
 /**
- * Mail Configuration (template)
+ * Mail Configuration (default override)
  *
  * Keep this file declarative:
  * - Core owns env parsing/default logic.
- * - Projects can override values by editing `drivers` and `mailConfigObj`.
+ * - Projects can override config by editing values below.
  */
 
-import { mailConfig as coreMailConfig } from '@zintrust/core';
+export default {
+  default: Env.get('MAIL_CONNECTION', Env.get('MAIL_DRIVER', 'disabled')).trim().toLowerCase(),
+  from: {
+    address: Env.get('MAIL_FROM_ADDRESS', ''),
+    name: Env.get('MAIL_FROM_NAME', ''),
+  },
+  drivers: {
+    disabled: {
+      driver: 'disabled' as const,
+    },
+
+    sendgrid: {
+      driver: 'sendgrid' as const,
+      apiKey: Env.get('SENDGRID_API_KEY', ''),
+    },
 
-type MailConfigShape = typeof coreMailConfig;
+    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(),
+    },
 
-export const drivers = {
-  ...coreMailConfig.drivers,
-} satisfies MailConfigShape['drivers'];
+    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);
+      })(),
+    },
 
-export const mailConfigObj = {
-  ...coreMailConfig,
-  drivers,
-} satisfies MailConfigShape;
+    nodemailer: {
+      driver: 'nodemailer' 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);
+      })(),
+    },
 
-export const mailConfig = mailConfigObj;
-export type MailConfig = typeof mailConfig;
+    ses: {
+      driver: 'ses' as const,
+      region: Env.get('AWS_REGION', 'us-east-1'),
+    },
+  },
+} satisfies MailConfigOverrides;

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

@@ -1,23 +1,34 @@
+import { Env, type NotificationConfigOverrides } from '@zintrust/core';
+
 /**
- * Notification Configuration (template)
+ * Notification Configuration (default override)
  *
  * Keep this file declarative:
  * - Core owns env parsing/default logic.
- * - Projects can override values by editing `drivers` and `notificationConfigObj`.
+ * - Projects can override config by editing values below.
  */
 
-import { notificationConfig as coreNotificationConfig } from '@zintrust/core';
-
-type NotificationConfigShape = typeof coreNotificationConfig;
-
-export const drivers = {
-  ...coreNotificationConfig.drivers,
-} satisfies NotificationConfigShape['drivers'];
-
-export const notificationConfigObj = {
-  ...coreNotificationConfig,
-  drivers,
-} satisfies NotificationConfigShape;
-
-const notificationConfig = notificationConfigObj;
-export default notificationConfig;
+export default {
+  default: Env.get('NOTIFICATION_CONNECTION', Env.get('NOTIFICATION_DRIVER', 'console')),
+  drivers: {
+    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 NotificationConfigOverrides;

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

@@ -1,23 +1,55 @@
+import { Env, type QueueConfigOverrides, type QueueDriverName } from '@zintrust/core';
+
 /**
- * Queue Configuration (template)
+ * Queue Configuration (default override)
  *
  * Keep this file declarative:
  * - Core owns env parsing/default logic.
- * - Projects can override values by editing `connections` and `queueConfigObj`.
+ * - Projects can override config by editing values below.
  */
 
-import { queueConfig as coreQueueConfig } from '@zintrust/core';
-
-type QueueConfigShape = typeof coreQueueConfig;
-
-export const connections = {
-  ...coreQueueConfig.connections,
-} satisfies QueueConfigShape['connections'];
-
-export const queueConfigObj = {
-  ...coreQueueConfig,
-  connections,
-} satisfies QueueConfigShape;
-
-const queueConfig = queueConfigObj;
-export default queueConfig;
+export default {
+  default: Env.get('QUEUE_DRIVER', 'sync') as QueueDriverName,
+  drivers: {
+    sync: {
+      driver: 'sync' as const,
+    },
+    database: {
+      driver: 'database' as const,
+      table: Env.get('QUEUE_TABLE', 'jobs'),
+      connection: Env.get('QUEUE_DB_CONNECTION', 'default'),
+    },
+    redis: {
+      driver: 'redis' as const,
+      host: Env.get('REDIS_HOST', 'localhost'),
+      port: Env.getInt('REDIS_PORT', 6379),
+      password: Env.get('REDIS_PASSWORD'),
+      database: Env.getInt('REDIS_QUEUE_DB', 1),
+    },
+    rabbitmq: {
+      driver: 'rabbitmq' as const,
+      host: Env.get('RABBITMQ_HOST', 'localhost'),
+      port: Env.getInt('RABBITMQ_PORT', 5672),
+      username: Env.get('RABBITMQ_USER', 'guest'),
+      password: Env.get('RABBITMQ_PASSWORD', 'guest'),
+      vhost: Env.get('RABBITMQ_VHOST', '/'),
+    },
+    sqs: {
+      driver: 'sqs' as const,
+      key: Env.get('AWS_ACCESS_KEY_ID'),
+      secret: Env.get('AWS_SECRET_ACCESS_KEY'),
+      region: Env.AWS_REGION,
+      queueUrl: Env.get('AWS_SQS_QUEUE_URL'),
+    },
+  },
+  failed: {
+    database: Env.get('FAILED_JOBS_DB_CONNECTION', 'default'),
+    table: Env.get('FAILED_JOBS_TABLE', 'failed_jobs'),
+  },
+  processing: {
+    timeout: Env.getInt('QUEUE_JOB_TIMEOUT', 60),
+    retries: Env.getInt('QUEUE_JOB_RETRIES', 3),
+    backoff: Env.getInt('QUEUE_JOB_BACKOFF', 0),
+    workers: Env.getInt('QUEUE_WORKERS', 1),
+  },
+} satisfies QueueConfigOverrides;

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

@@ -1,23 +1,60 @@
+import { Env, type StorageConfigOverrides } from '@zintrust/core';
+
 /**
- * Storage Configuration (template)
+ * Storage Configuration (default override)
  *
  * Keep this file declarative:
- * - Core owns env parsing/default logic.
- * - Projects can override values by editing `drivers` and `storageConfigObj`.
+ * - Core owns driver setup and env parsing/default logic.
+ * - Projects can override config by editing values below.
  */
 
-import { storageConfig as coreStorageConfig } from '@zintrust/core';
-
-type StorageConfigShape = typeof coreStorageConfig;
-
-export const drivers = {
-  ...coreStorageConfig.drivers,
-} satisfies StorageConfigShape['drivers'];
-
-export const storageConfigObj = {
-  ...coreStorageConfig,
-  drivers,
-} satisfies StorageConfigShape;
-
-export const storageConfig = storageConfigObj;
-export type StorageConfig = typeof storageConfig;
+export default {
+  default: Env.get('STORAGE_CONNECTION', Env.get('STORAGE_DRIVER', 'local')).trim().toLowerCase(),
+  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,
+      accessKeyId: Env.get('AWS_ACCESS_KEY_ID', ''),
+      secretAccessKey: Env.get('AWS_SECRET_ACCESS_KEY', ''),
+      region: Env.get('AWS_REGION', 'us-east-1'),
+      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', ''),
+    },
+  },
+  temp: {
+    path: Env.get('TEMP_PATH', 'storage/temp'),
+    maxAge: Env.getInt('TEMP_FILE_MAX_AGE', 86400),
+  },
+  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'),
+  },
+  backups: {
+    path: Env.get('BACKUPS_PATH', 'storage/backups'),
+    driver: Env.get('BACKUP_DRIVER', 's3'),
+  },
+} satisfies StorageConfigOverrides;

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

@@ -28,7 +28,6 @@ export type {
   NotificationDrivers,
   ProcessLike,
   QueueConfig,
-  QueueConfigInput,
   StorageConfig,
   StorageConfigRuntime,
   StorageDriverConfig,

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

@@ -4,6 +4,9 @@
 
 import { isNodeMain, start } from '@zintrust/core/start';
 
+// Register plugins (side-effects)
+import './zintrust.plugins';
+
 // Cloudflare Workers entry.
 export { default } from '@zintrust/core/start';
 

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

@@ -1,181 +0,0 @@
-/**
- * KV Logger
- * Writes batches of log events to a KV namespace (Cloudflare Workers compatible)
- *
- * Enabled via env:
- *  - KV_LOG_ENABLED (default: false)
- *  - KV_NAMESPACE (binding name; default: 'CACHE')
- *  - KV_LOG_RETENTION_DAYS (default: 30)
- */
-
-import { Cloudflare } from '@zintrust/core';
-import { Env } from '@zintrust/core';
-
-export type KvLogEvent = {
-  timestamp: string;
-  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
-  message: string;
-  category?: string;
-  data?: unknown;
-  error?: string;
-};
-
-type KVNamespace = NonNullable<ReturnType<typeof Cloudflare.getKVBinding>>;
-
-type PutOptions = { expiration?: number; expirationTtl?: number; metadata?: unknown };
-
-const getRetentionTtlSeconds = (): number => {
-  const days = Env.getInt('KV_LOG_RETENTION_DAYS', 30);
-  const safeDays = Number.isFinite(days) && days > 0 ? days : 30;
-  return safeDays * 24 * 60 * 60;
-};
-
-const getKvBindingName = (): string => {
-  const name = Env.get('KV_NAMESPACE', 'CACHE').trim();
-  return name.length > 0 ? name : 'CACHE';
-};
-
-const isEnabled = (): boolean => Env.getBool('KV_LOG_ENABLED', false);
-
-const safeRandom = (): string => {
-  try {
-    // Prefer crypto if available
-    const cryptoObj = (globalThis as unknown as { crypto?: Crypto }).crypto;
-    if (cryptoObj?.getRandomValues) {
-      const bytes = new Uint8Array(8);
-      cryptoObj.getRandomValues(bytes);
-      return Array.from(bytes)
-        .map((b) => b.toString(16).padStart(2, '0'))
-        .join('');
-    }
-  } catch {
-    // fall through
-  }
-  const generate = Math.random().toString(16).slice(2); // NOSONAR
-  const fallback = generate + Math.random().toString(16).slice(2); // NOSONAR this is not used for security
-  return fallback;
-};
-
-const buildKey = (timestampIso: string): string => {
-  const date = timestampIso.slice(0, 10);
-  const hour = timestampIso.slice(11, 13);
-  return `logs:${date}:${hour}:${safeRandom()}`;
-};
-
-let buffer: KvLogEvent[] = [];
-let flushTimer: ReturnType<typeof setTimeout> | undefined;
-let flushPromise: Promise<void> | undefined;
-
-const scheduleFlush = async (): Promise<void> => {
-  if (flushPromise !== undefined) return flushPromise;
-
-  // Fixed small batching window to reduce KV write volume.
-  const windowMs = 1000;
-
-  const promise = new Promise<void>((resolve) => {
-    const run = async (): Promise<void> => {
-      try {
-        await flushNow();
-      } finally {
-        resolve(undefined);
-      }
-    };
-
-    if (typeof globalThis.setTimeout !== 'function') {
-      // microtask-ish
-      void run();
-      return;
-    }
-
-    flushTimer = globalThis.setTimeout(() => {
-      flushTimer = undefined;
-      void run();
-    }, windowMs);
-  });
-
-  flushPromise = promise.finally(() => {
-    flushPromise = undefined;
-  });
-
-  return flushPromise;
-};
-
-const getKv = (): KVNamespace | null => {
-  const bindingName = getKvBindingName();
-  return Cloudflare.getKVBinding(bindingName);
-};
-
-const putBatch = async (kv: KVNamespace, events: KvLogEvent[]): Promise<void> => {
-  if (events.length === 0) return;
-
-  const timestamp = events.at(-1)?.timestamp ?? new Date().toISOString();
-  const key = buildKey(timestamp);
-
-  const payload = JSON.stringify({
-    version: 1,
-    createdAt: new Date().toISOString(),
-    count: events.length,
-    events,
-  });
-
-  const opts: PutOptions = { expirationTtl: getRetentionTtlSeconds() };
-
-  await kv.put(key, payload, opts);
-};
-
-const flushNow = async (): Promise<void> => {
-  if (!isEnabled()) {
-    buffer = [];
-    return;
-  }
-
-  const kv = getKv();
-  if (kv === null) {
-    buffer = [];
-    return;
-  }
-
-  const toSend = buffer;
-  buffer = [];
-
-  try {
-    await putBatch(kv, toSend);
-  } catch {
-    // Best-effort: never throw from logging.
-  }
-};
-
-const flushSoon = async (): Promise<void> => {
-  if (flushPromise !== undefined) return flushPromise;
-
-  flushPromise = Promise.resolve()
-    .then(async () => flushNow())
-    .finally(() => {
-      flushPromise = undefined;
-    });
-
-  return flushPromise;
-};
-
-export const KvLogger = Object.freeze({
-  async enqueue(event: KvLogEvent): Promise<void> {
-    if (!isEnabled()) return Promise.resolve();
-
-    buffer.push(event);
-
-    // Basic size guard: flush if it gets too large
-    const maxBatch = 100;
-    if (buffer.length >= maxBatch) {
-      // Cancel scheduled flush and flush immediately
-      if (flushTimer !== undefined) {
-        globalThis.clearTimeout(flushTimer);
-        flushTimer = undefined;
-      }
-      return flushSoon();
-    }
-
-    return scheduleFlush();
-  },
-});
-
-export default KvLogger;