@zintrust/core 0.1.27 → 0.1.28

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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,43 @@
+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

@@ -0,0 +1,77 @@
+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

@@ -0,0 +1,19 @@
+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

@@ -0,0 +1,49 @@
+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

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

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

@@ -0,0 +1,45 @@
+import { readdirSync, statSync } from '@node-singletons/fs';
+import { join, relative } from '@node-singletons/path';
+import { loadTemplate } from '@notification/templates/markdown';
+import { MarkdownRenderer } from '@tools/templates';
+
+const BASE = join(process.cwd(), 'src', 'tools', 'notification', 'templates', 'markdown');
+
+const walkDir = (dir: string, base = dir): string[] => {
+  const entries = readdirSync(dir);
+  let files: string[] = [];
+  for (const e of entries) {
+    const p = join(dir, e);
+    const s = statSync(p);
+    if (s.isDirectory()) {
+      files = files.concat(walkDir(p, base));
+      continue;
+    }
+    if (e.endsWith('.md')) {
+      const rel = relative(base, p).replaceAll('\\', '/');
+      const withoutExt = rel.toLowerCase().endsWith('.md') ? rel.slice(0, -3) : rel;
+      files.push(withoutExt);
+    }
+  }
+  return files;
+};
+
+export const listTemplates = (): string[] => {
+  return walkDir(BASE);
+};
+
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+export const renderTemplate = (
+  name: string,
+  vars: Record<string, unknown> = {}
+): { html: string; meta: ReturnType<typeof loadTemplate> } => {
+  const tpl = loadTemplate(name);
+  // Basic validation: subject required
+  if (tpl.subject === null || tpl.subject === undefined || tpl.subject.trim() === '')
+    throw ErrorFactory.createValidationError('Notification template missing subject', { name });
+  const html = MarkdownRenderer.render(tpl.content, vars);
+  return { html, meta: tpl };
+};
+
+export default { listTemplates, renderTemplate };

package/src/tools/notification/testing.ts

@@ -0,0 +1,50 @@
+import { ErrorFactory } from '@exceptions/ZintrustError';
+
+type SentRecord = {
+  provider: string;
+  payload: unknown;
+  config: unknown;
+};
+
+export const NotificationFake = Object.freeze({
+  _sent: [] as Array<SentRecord>,
+
+  async send(provider: string, config: unknown, payload: unknown): Promise<{ ok: boolean }> {
+    this._sent.push({ provider, config, payload });
+    await Promise.resolve();
+    return { ok: true };
+  },
+
+  assertSent(predicate: (r: SentRecord) => boolean) {
+    if (!this._sent.some(predicate))
+      throw ErrorFactory.createValidationError('Expected notification to be sent');
+  },
+
+  assertNotSent(predicate: (r: SentRecord) => boolean) {
+    if (this._sent.some(predicate))
+      throw ErrorFactory.createValidationError('Expected notification to NOT be sent');
+  },
+
+  assertSentCount(expected: number) {
+    if (this._sent.length !== expected) {
+      throw ErrorFactory.createValidationError('Unexpected notification send count', {
+        expected,
+        actual: this._sent.length,
+      });
+    }
+  },
+
+  getSent(): Array<SentRecord> {
+    return [...this._sent];
+  },
+
+  lastSent(): SentRecord | undefined {
+    return this._sent.length > 0 ? this._sent.at(-1) : undefined;
+  },
+
+  reset() {
+    this._sent.length = 0;
+  },
+});
+
+export default NotificationFake;

package/src/tools/notification/testingHelpers.ts

@@ -0,0 +1,44 @@
+import { NotificationRegistry } from '@notification/Registry';
+import NotificationFake from '@notification/testing';
+
+// NOTE: This testing helper intentionally uses direct process.env mutations
+// to temporarily override NOTIFICATION_DRIVER for test isolation.
+// This is an exception to the Env singleton pattern.
+
+type DriverLike = {
+  send(recipient: string, message: string, options?: Record<string, unknown>): Promise<unknown>;
+};
+
+export const useFakeDriver = (
+  name = 'notification-fake',
+  fake: unknown = NotificationFake
+): { driverName: string; restore: () => void } => {
+  let previous: DriverLike | undefined;
+  try {
+    previous = NotificationRegistry.get(name) as DriverLike;
+  } catch {
+    previous = undefined;
+  }
+
+  const fakeDriver = fake as DriverLike;
+  NotificationRegistry.register(name, fakeDriver);
+  const prevEnv = process.env['NOTIFICATION_DRIVER'];
+  process.env['NOTIFICATION_DRIVER'] = name;
+
+  return {
+    driverName: name,
+    restore() {
+      // Restore previous driver if present, otherwise keep fake registered
+      if (previous === undefined) {
+        NotificationRegistry.register(name, NotificationFake as unknown as DriverLike);
+      } else {
+        NotificationRegistry.register(name, previous);
+      }
+
+      if (prevEnv === undefined) delete process.env['NOTIFICATION_DRIVER'];
+      else process.env['NOTIFICATION_DRIVER'] = prevEnv;
+    },
+  };
+};
+
+export default { useFakeDriver };