@zintrust/core 0.4.17 → 0.4.19

package/src/tools/mail/testing.ts

@@ -1,59 +0,0 @@
-import { ErrorFactory } from '@exceptions/ZintrustError';
-
-type SentRecord = {
-  to: string[];
-  subject: string;
-  text: string;
-  html?: string;
-  from?: { address?: string; name?: string };
-  attachments?: Array<{ filename: string; content: Buffer }>;
-};
-
-type FakeSendInput = {
-  to: string | string[];
-  subject: string;
-  text: string;
-  html?: string;
-  from?: { address?: string; name?: string };
-  attachments?: Array<{ filename: string; content: Buffer }>;
-};
-
-export const MailFake = Object.freeze({
-  _sent: [] as Array<SentRecord>,
-
-  async send(input: FakeSendInput): Promise<{ ok: boolean; driver: string }> {
-    const to = Array.isArray(input.to) ? input.to : [input.to];
-    this._sent.push({
-      to,
-      subject: input.subject,
-      text: input.text,
-      html: input.html,
-      from: input.from,
-      attachments: input.attachments,
-    });
-    await Promise.resolve();
-    return { ok: true, driver: 'disabled' };
-  },
-
-  assertSent(predicate: (r: SentRecord) => boolean) {
-    if (!this._sent.some(predicate)) {
-      throw ErrorFactory.createValidationError('Expected a sent mail matching predicate');
-    }
-  },
-
-  assertNotSent(predicate: (r: SentRecord) => boolean) {
-    if (this._sent.some(predicate)) {
-      throw ErrorFactory.createValidationError('Expected no sent mail matching predicate');
-    }
-  },
-
-  getSent() {
-    return this._sent.slice();
-  },
-
-  reset() {
-    this._sent.length = 0;
-  },
-});
-
-export default MailFake;

package/src/tools/notification/Driver.ts

@@ -1,11 +0,0 @@
-export interface INotificationDriver {
-  send(recipient: string, message: string, options?: Record<string, unknown>): Promise<unknown>;
-}
-
-export type NotificationPayload = {
-  recipient: string;
-  message: string;
-  options?: Record<string, unknown>;
-};
-
-export default {} as unknown as INotificationDriver;

package/src/tools/notification/Notification.ts

@@ -1,55 +0,0 @@
-/**
- * Notification - Public API entry point
- *
- * A small wrapper over NotificationService to provide the expected module name.
- */
-
-import { NotificationService } from '@notification/Service';
-
-export const Notification = Object.freeze({
-  send: NotificationService.send,
-
-  // Alias for send() - explicit intent for immediate notification
-  NotifyNow: NotificationService.send,
-
-  // Queue notification for async processing
-  async NotifyLater(
-    recipient: string,
-    message: string,
-    notifyOptions: Record<string, unknown> = {},
-    queueOptions: { queueName?: string; timestamp?: number } = {}
-  ): Promise<string> {
-    const { queueName = 'notifications', timestamp = Date.now() } = queueOptions;
-    const { Queue } = await import('@tools/queue/Queue');
-    const messageId = await Queue.enqueue(queueName, {
-      type: 'notification',
-      recipient,
-      message,
-      options: notifyOptions,
-      timestamp,
-      attempts: 0,
-    });
-    return messageId ?? '';
-  },
-
-  queue(queueName: string) {
-    return Object.freeze({
-      NotifyLater: async (
-        recipient: string,
-        message: string,
-        notifyOptions: Record<string, unknown> = {},
-        queueOptions: { timestamp?: number } = {}
-      ) =>
-        Notification.NotifyLater(recipient, message, notifyOptions, { ...queueOptions, queueName }),
-    });
-  },
-
-  channel: (name: string) =>
-    Object.freeze({
-      send: async (recipient: string, message: string, options?: Record<string, unknown>) =>
-        NotificationService.sendVia(name, recipient, message, options),
-    }),
-  listDrivers: NotificationService.listDrivers,
-});
-
-export default Notification;

package/src/tools/notification/NotificationChannelRegistry.ts

@@ -1,46 +0,0 @@
-import type { KnownNotificationDriverConfig } from '@config/type';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-
-const registry = new Map<string, KnownNotificationDriverConfig>();
-
-const normalizeKey = (name: string): string =>
-  String(name ?? '')
-    .trim()
-    .toLowerCase();
-
-function register(name: string, config: KnownNotificationDriverConfig): void {
-  const key = normalizeKey(name);
-  if (key === '') return;
-  registry.set(key, config);
-}
-
-function has(name: string): boolean {
-  return registry.has(normalizeKey(name));
-}
-
-function get(name: string): KnownNotificationDriverConfig {
-  const key = normalizeKey(name);
-  const cfg = registry.get(key);
-  if (cfg === undefined) {
-    throw ErrorFactory.createConfigError(`Notification channel not registered: ${name}`);
-  }
-  return cfg;
-}
-
-function list(): string[] {
-  return Array.from(registry.keys()).sort((a, b) => a.localeCompare(b));
-}
-
-function reset(): void {
-  registry.clear();
-}
-
-export const NotificationChannelRegistry = Object.freeze({
-  register,
-  has,
-  get,
-  list,
-  reset,
-});
-
-export default NotificationChannelRegistry;

package/src/tools/notification/NotificationRuntimeRegistration.ts

@@ -1,36 +0,0 @@
-import type { NotificationConfigInput } from '@config/type';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import { NotificationChannelRegistry } from '@notification/NotificationChannelRegistry';
-
-/**
- * Register notification channels from runtime config.
- *
- * - Every `notificationConfig.drivers[name]` is registered under `name`.
- * - The configured default is also registered as `default`.
- */
-export function registerNotificationChannelsFromRuntimeConfig(
-  config: Pick<NotificationConfigInput, 'default' | 'drivers'>
-): void {
-  for (const [name, driverConfig] of Object.entries(config.drivers)) {
-    NotificationChannelRegistry.register(name, driverConfig);
-  }
-
-  const defaultName = (config.default ?? '').toString().trim().toLowerCase();
-  if (defaultName.length === 0) {
-    throw ErrorFactory.createConfigError('Notification default channel is not configured');
-  }
-
-  if (!NotificationChannelRegistry.has(defaultName)) {
-    throw ErrorFactory.createConfigError(
-      `Notification default channel not configured: ${defaultName}`
-    );
-  }
-
-  NotificationChannelRegistry.register('default', NotificationChannelRegistry.get(defaultName));
-}
-
-export const NotificationRuntimeRegistration = Object.freeze({
-  registerNotificationChannelsFromRuntimeConfig,
-});
-
-export default NotificationRuntimeRegistration;

package/src/tools/notification/Registry.ts

@@ -1,35 +0,0 @@
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import { ConsoleDriver } from '@notification/drivers/Console';
-import { SlackNotificationDriver } from '@notification/drivers/SlackNotification';
-import { TermiiDriver } from '@notification/drivers/Termii';
-import { TwilioNotificationDriver } from '@notification/drivers/TwilioNotification';
-
-type DriverLike = {
-  send(recipient: string, message: string, options?: Record<string, unknown>): Promise<unknown>;
-};
-
-const drivers = new Map<string, DriverLike>();
-
-drivers.set('termii', TermiiDriver);
-drivers.set('console', ConsoleDriver);
-drivers.set('slack', SlackNotificationDriver);
-drivers.set('twilio', TwilioNotificationDriver);
-
-export const NotificationRegistry = Object.freeze({
-  register(name: string, driver: DriverLike) {
-    drivers.set(name.toLowerCase(), driver);
-  },
-
-  get(name: string): DriverLike {
-    const key = (name ?? '').toString().trim().toLowerCase();
-    const drv = drivers.get(key);
-    if (!drv) throw ErrorFactory.createConfigError(`Notification driver not registered: ${name}`);
-    return drv;
-  },
-
-  list(): string[] {
-    return Array.from(drivers.keys()).sort((a, b) => a.localeCompare(b));
-  },
-});
-
-export default NotificationRegistry;

package/src/tools/notification/Service.ts

@@ -1,136 +0,0 @@
-import notificationConfig from '@config/notification';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-import { NotificationConfig } from '@notification/config';
-import { ConsoleDriver } from '@notification/drivers/Console';
-import { SlackDriver } from '@notification/drivers/Slack';
-import { TwilioDriver } from '@notification/drivers/Twilio';
-import { NotificationChannelRegistry } from '@notification/NotificationChannelRegistry';
-import { NotificationRegistry } from '@notification/Registry';
-
-const assertValidRecipientAndMessage = (recipient: unknown, message: unknown): void => {
-  if (typeof recipient !== 'string' || recipient.trim() === '') {
-    throw ErrorFactory.createValidationError('Recipient required');
-  }
-  if (typeof message !== 'string' || message.trim() === '') {
-    throw ErrorFactory.createValidationError('Message required');
-  }
-};
-
-const resolveChannelConfig = (channelName: string): unknown => {
-  const selected = String(channelName ?? '').trim();
-  const hasSelection = selected.length > 0;
-
-  return hasSelection && NotificationChannelRegistry.has(selected)
-    ? NotificationChannelRegistry.get(selected)
-    : notificationConfig.getDriverConfig(selected);
-};
-
-const sendTermii = async (
-  cfg: { apiKey?: unknown; sender?: unknown; endpoint?: unknown },
-  recipient: string,
-  message: string,
-  options: Record<string, unknown>
-): Promise<unknown> => {
-  const apiKey = String(cfg.apiKey ?? '');
-  if (apiKey.trim() === '') {
-    throw ErrorFactory.createConfigError('TERMII_API_KEY is not configured');
-  }
-
-  const url = String(cfg.endpoint ?? '').trim();
-  if (url === '') {
-    throw ErrorFactory.createConfigError('TERMII_ENDPOINT is not configured');
-  }
-
-  const payload = {
-    to: recipient,
-    from: cfg.sender,
-    sms: message,
-    api_key: apiKey,
-    ...options,
-  } as Record<string, unknown>;
-
-  const res = await globalThis.fetch(url, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(payload),
-  });
-
-  if (!res.ok) {
-    const txt = await res.text().catch(() => '');
-    throw ErrorFactory.createTryCatchError(`Termii request failed (${res.status})`, {
-      status: res.status,
-      body: txt,
-    });
-  }
-
-  return res.json().catch(() => ({}));
-};
-
-export const NotificationService = Object.freeze({
-  async send(recipient: string, message: string, options: Record<string, unknown> = {}) {
-    assertValidRecipientAndMessage(recipient, message);
-
-    const driverName = NotificationConfig.getDriver();
-    const driver = NotificationRegistry.get(driverName);
-
-    return driver.send(recipient, message, options);
-  },
-
-  async sendVia(
-    channelName: string,
-    recipient: string,
-    message: string,
-    options: Record<string, unknown> = {}
-  ) {
-    assertValidRecipientAndMessage(recipient, message);
-
-    const cfg = resolveChannelConfig(channelName) as { driver?: unknown };
-
-    switch (cfg.driver) {
-      case 'console':
-        return ConsoleDriver.send(recipient, message, options);
-
-      case 'slack': {
-        const slackCfg = cfg as { webhookUrl: string };
-        const payload: Record<string, unknown> = { text: message, ...options };
-        return SlackDriver.send({ webhookUrl: slackCfg.webhookUrl }, payload);
-      }
-
-      case 'twilio': {
-        const twilioCfg = cfg as {
-          accountSid: string;
-          authToken: string;
-          fromNumber: string;
-        };
-        return TwilioDriver.send(
-          {
-            accountSid: twilioCfg.accountSid,
-            authToken: twilioCfg.authToken,
-            from: twilioCfg.fromNumber,
-          },
-          { to: recipient, body: message }
-        );
-      }
-
-      case 'termii': {
-        return sendTermii(
-          cfg as { apiKey?: unknown; sender?: unknown; endpoint?: unknown },
-          recipient,
-          message,
-          options
-        );
-      }
-
-      default:
-        throw ErrorFactory.createConfigError(
-          `Notification: unsupported driver: ${String((cfg as { driver?: unknown })?.driver)}`
-        );
-    }
-  },
-
-  listDrivers(): string[] {
-    return NotificationRegistry.list();
-  },
-});
-
-export default NotificationService;

package/src/tools/notification/config.ts

@@ -1,7 +0,0 @@
-import { Env } from '@config/env';
-
-export const NotificationConfig = Object.freeze({
-  getDriver: (): string => Env.get('NOTIFICATION_DRIVER', 'console').trim().toLowerCase(),
-});
-
-export default NotificationConfig;

package/src/tools/notification/drivers/BaseDriver.ts

@@ -1,10 +0,0 @@
-import { ErrorFactory } from '@exceptions/ZintrustError';
-
-export const BaseDriver = Object.freeze({
-  async send(): Promise<unknown> {
-    await Promise.resolve();
-    throw ErrorFactory.createConfigError('Notification driver must implement send()');
-  },
-});
-
-export default BaseDriver;

package/src/tools/notification/drivers/Console.ts

@@ -1,18 +0,0 @@
-export const ConsoleDriver = Object.freeze({
-  async send(
-    _recipient: string,
-    _message: string,
-    _options: Record<string, unknown> = {}
-  ): Promise<{ ok: boolean }> {
-    // Console driver is for development & simple systems — it should not throw
-    // Keep implementation minimal and synchronous-friendly
-    // Use out of band logging via ErrorHandler/Logger if required by callers
-    // Here we simply return a small payload indicating success
-    // Example: { ok: true }
-    // NOTE: keep body small to avoid leaking test runner logs
-    await Promise.resolve();
-    return { ok: true };
-  },
-});
-
-export default ConsoleDriver;

package/src/tools/notification/drivers/Slack.ts

@@ -1,42 +0,0 @@
-import { ErrorFactory } from '@exceptions/ZintrustError';
-
-export type SlackConfig = {
-  webhookUrl: string;
-};
-
-export type SlackMessage = Record<string, unknown>;
-
-export const SlackDriver = Object.freeze({
-  async send(
-    config: SlackConfig,
-    payload: SlackMessage
-  ): Promise<{ ok: boolean; status?: number }> {
-    const url = config.webhookUrl ?? '';
-    if (typeof url !== 'string' || url.trim() === '') {
-      throw ErrorFactory.createConfigError('Slack: missing webhook URL');
-    }
-
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify(payload),
-    });
-
-    if (!res.ok) {
-      const text = await res.text();
-      throw ErrorFactory.createConnectionError(`Slack webhook failed (${res.status})`, {
-        status: res.status,
-        body: text,
-      });
-    }
-
-    return { ok: true, status: res.status };
-  },
-});
-
-export const sendSlackWebhook = async (
-  config: SlackConfig,
-  payload: SlackMessage
-): Promise<{ ok: boolean; status?: number }> => SlackDriver.send(config, payload);
-
-export default SlackDriver;

package/src/tools/notification/drivers/SlackNotification.ts

@@ -1,17 +0,0 @@
-import notificationConfig from '@config/notification';
-import { SlackDriver } from '@notification/drivers/Slack';
-
-export const SlackNotificationDriver = Object.freeze({
-  async send(_recipient: string, message: string, options: Record<string, unknown> = {}) {
-    const cfg = notificationConfig.providers.slack;
-
-    const payload: Record<string, unknown> = {
-      text: message,
-      ...options,
-    };
-
-    return SlackDriver.send({ webhookUrl: cfg.webhookUrl }, payload);
-  },
-});
-
-export default SlackNotificationDriver;

package/src/tools/notification/drivers/Termii.ts

@@ -1,43 +0,0 @@
-import { readEnvString, safeFetch, validateRequiredParams } from '@common/ExternalServiceUtils';
-import { ErrorFactory } from '@exceptions/ZintrustError';
-
-/**
- * Termii SMS Driver (skeleton)
- * - Reads TERMII_API_KEY and TERMII_SENDER from env
- * - POSTs to Termii API endpoint
- */
-export const TermiiDriver = Object.freeze({
-  async send(recipient: string, message: string, options: Record<string, unknown> = {}) {
-    validateRequiredParams({ recipient, message }, ['recipient', 'message']);
-
-    const apiKey = readEnvString('TERMII_API_KEY');
-    const sender = readEnvString('TERMII_SENDER');
-
-    if (!apiKey) {
-      throw ErrorFactory.createConfigError('TERMII_API_KEY is not configured');
-    }
-
-    const payload = {
-      to: recipient,
-      from: sender,
-      sms: message,
-      api_key: apiKey,
-      ...options,
-    } as Record<string, unknown>;
-
-    // Use shared fetch wrapper
-    const url = 'https://api.termii.com/sms/send';
-    const res = await safeFetch(url, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(payload),
-    });
-
-    const json = await res.json().catch(() => ({}));
-    return json;
-  },
-});
-
-export default TermiiDriver;

package/src/tools/notification/drivers/Twilio.ts

@@ -1,77 +0,0 @@
-import { ErrorFactory } from '@exceptions/ZintrustError';
-
-export type TwilioConfig = {
-  accountSid: string;
-  authToken: string;
-  from: string;
-};
-
-export type TwilioMessage = {
-  to: string;
-  body: string;
-};
-
-const buildUrl = (accountSid: string): string => {
-  const base = 'https://api.twilio.com/2010-04-01/Accounts/';
-  return `${base}${accountSid}/Messages.json`;
-};
-
-export const TwilioDriver = Object.freeze({
-  async send(
-    config: TwilioConfig,
-    payload: TwilioMessage
-  ): Promise<{ ok: boolean; status?: number }> {
-    const accountSid = config.accountSid ?? '';
-    const authToken = config.authToken ?? '';
-    const from = config.from ?? '';
-
-    if (typeof accountSid !== 'string' || accountSid.trim() === '') {
-      throw ErrorFactory.createConfigError('Twilio: missing accountSid');
-    }
-    if (typeof authToken !== 'string' || authToken.trim() === '') {
-      throw ErrorFactory.createConfigError('Twilio: missing authToken');
-    }
-    if (typeof from !== 'string' || from.trim() === '') {
-      throw ErrorFactory.createConfigError('Twilio: missing from number');
-    }
-
-    if (typeof payload.to !== 'string' || payload.to.trim() === '') {
-      throw ErrorFactory.createValidationError('Twilio: missing to number');
-    }
-
-    const url = buildUrl(accountSid);
-
-    const params = new URLSearchParams();
-    params.append('To', payload.to);
-    params.append('From', from);
-    params.append('Body', payload.body);
-
-    const basic = Buffer.from(`${accountSid}:${authToken}`).toString('base64');
-
-    const res = await fetch(url, {
-      method: 'POST',
-      headers: {
-        Authorization: `Basic ${basic}`,
-        'content-type': 'application/x-www-form-urlencoded',
-      },
-      body: params.toString(),
-    });
-
-    if (!res.ok) {
-      const body = await res.text();
-      throw ErrorFactory.createConnectionError(`Twilio API failed (${res.status})`, {
-        status: res.status,
-        body,
-      });
-    }
-
-    return { ok: true, status: res.status };
-  },
-});
-
-export const sendSms = async (
-  config: TwilioConfig,
-  payload: TwilioMessage
-): Promise<{ ok: boolean; status?: number }> => TwilioDriver.send(config, payload);
-
-export default TwilioDriver;

package/src/tools/notification/drivers/TwilioNotification.ts

@@ -1,19 +0,0 @@
-import notificationConfig from '@config/notification';
-import { TwilioDriver } from '@notification/drivers/Twilio';
-
-export const TwilioNotificationDriver = Object.freeze({
-  async send(recipient: string, message: string) {
-    const cfg = notificationConfig.providers.twilio;
-
-    return TwilioDriver.send(
-      {
-        accountSid: cfg.accountSid,
-        authToken: cfg.authToken,
-        from: cfg.fromNumber,
-      },
-      { to: recipient, body: message }
-    );
-  },
-});
-
-export default TwilioNotificationDriver;

package/src/tools/notification/templates/markdown/index.ts

@@ -1,49 +0,0 @@
-import { readFileSync } from '@node-singletons/fs';
-import { join } from '@node-singletons/path';
-
-export const loadTemplate = (
-  name: string
-): { subject?: string; content: string; variables?: string[] } => {
-  const parts = name.split('/');
-  const dir = join(
-    process.cwd(),
-    'src',
-    'tools',
-    'notification',
-    'templates',
-    'markdown',
-    ...parts.slice(0, -1)
-  );
-  const leaf = parts.at(-1) ?? '';
-  const filePath = join(dir, `${leaf}.md`);
-  const raw = readFileSync(filePath, 'utf-8');
-
-  const meta: { subject?: string; variables?: string[] } = {};
-  const lines = raw.split(/\r?\n/);
-  let i = 0;
-  for (; i < lines.length; i++) {
-    const line = lines[i].trim();
-    // Fast path: must look like an HTML comment and contain a colon separator.
-    if (!line.startsWith('<!--') || !line.endsWith('-->')) break;
-    const inner = line.slice(4, -3).trim();
-    const colonIndex = inner.indexOf(':');
-    if (colonIndex === -1) break;
-    const key = inner.slice(0, colonIndex).trim().toLowerCase();
-    const val = inner.slice(colonIndex + 1).trim();
-    if (!key) break;
-    if (key === 'subject') meta.subject = val;
-    if (key === 'variables') {
-      meta.variables = val
-        .split(',')
-        .map((s) => s.trim())
-        .filter(Boolean);
-    }
-  }
-
-  const content = lines.slice(i).join('\n').trim();
-  return { content, ...meta };
-};
-
-export { listTemplates, renderTemplate } from '@notification/templates/markdown/registry';
-
-export default { loadTemplate };

package/src/tools/notification/templates/markdown/notifications/new-follow.md

@@ -1,12 +0,0 @@
-<!-- Subject: New follower -->
-<!-- Variables: name, follower -->
-
-# New follower
-
-Hi {{name}},
-
-**{{follower}}** started following you.
-
----
-
-Open your profile to see their activity.