@zintrust/core 0.1.24 → 0.1.26

package/src/tools/mail/Mail.d.ts

@@ -1,30 +1,2 @@
-import { type AttachmentInput } from './attachments';
-export type SendMailInput = {
-    to: string | string[];
-    subject: string;
-    text: string;
-    html?: string;
-    from?: {
-        address?: string;
-        name?: string;
-    };
-    attachments?: AttachmentInput[];
-};
-export type SendMailResult = {
-    ok: boolean;
-    driver: 'sendgrid' | 'disabled' | 'smtp' | 'ses' | 'mailgun' | 'nodemailer';
-    messageId?: string;
-};
-export declare const Mail: Readonly<{
-    /**
-     * Select a named mailer (key from mailConfig.drivers).
-     *
-     * Example: `Mail.mailer('transactional').send(...)`
-     */
-    mailer(name: string): Readonly<{
-        send: (input: SendMailInput) => Promise<SendMailResult>;
-    }>;
-    send(input: SendMailInput): Promise<SendMailResult>;
-}>;
-export default Mail;
+export { default, Mail } from './index';
 //# sourceMappingURL=Mail.d.ts.map

package/src/tools/mail/Mail.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Mail.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/Mail.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI7E,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,YAAY,CAAC;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAoJF,eAAO,MAAM,IAAI;IACf;;;;OAIG;iBACU,MAAM;cAhCb,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC;;gBAoCrC,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;EAGzD,CAAC;AAEH,eAAe,IAAI,CAAC"}
+{"version":3,"file":"Mail.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/Mail.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC"}

package/src/tools/mail/Mail.js

@@ -1,111 +1 @@
-import { mailConfig } from '../../config/mail.js';
-import { ErrorFactory } from '../../exceptions/ZintrustError.js';
-import { SesDriver } from './drivers/Ses.js';
-import { resolveAttachments } from './attachments.js';
-import { MailDriverRegistry } from './MailDriverRegistry.js';
-import { Storage } from '../storage/index.js';
-const resolveFrom = (input) => {
-    const address = input?.address ?? mailConfig.from.address;
-    const name = input?.name ?? mailConfig.from.name;
-    if (address.trim() === '') {
-        const err = ErrorFactory.createConfigError('Mail: missing from address (set MAIL_FROM_ADDRESS or pass from.address)');
-        throw err;
-    }
-    return { email: address, name: name.trim() === '' ? undefined : name };
-};
-function assertStorageDiskLike(value) {
-    if (typeof value !== 'object' || value === null) {
-        const err = ErrorFactory.createConfigError('Storage disk is invalid (expected object)');
-        throw err;
-    }
-    const v = value;
-    const driver = v['driver'];
-    if (typeof driver !== 'object' || driver === null) {
-        const err = ErrorFactory.createConfigError('Storage disk driver is invalid (expected object)');
-        throw err;
-    }
-    const d = driver;
-    if (typeof d['get'] !== 'function') {
-        const err = ErrorFactory.createConfigError('Storage disk driver is missing get()');
-        throw err;
-    }
-    if (typeof d['exists'] !== 'function') {
-        const err = ErrorFactory.createConfigError('Storage disk driver is missing exists()');
-        throw err;
-    }
-}
-const getDiskSafe = (disk) => {
-    const diskValue = Storage.getDisk(disk);
-    assertStorageDiskLike(diskValue);
-    return diskValue;
-};
-const createStorageWrapper = () => ({
-    async get(disk, path) {
-        const d = getDiskSafe(disk);
-        const result = await Promise.resolve(d.driver.get(d.config, path));
-        return result;
-    },
-    async exists(disk, path) {
-        const d = getDiskSafe(disk);
-        const result = await Promise.resolve(d.driver.exists(d.config, path));
-        return Boolean(result);
-    },
-});
-const sendWithDriver = async (driver, message) => {
-    if (driver.driver === 'ses') {
-        const result = await SesDriver.send({ region: driver.region }, message);
-        return { ok: result.ok, driver: 'ses', messageId: result.messageId };
-    }
-    // Drivers resolve via MailDriverRegistry (external packages)
-    const external = MailDriverRegistry.get(driver.driver);
-    if (external !== undefined) {
-        const result = await external(driver, message);
-        return {
-            ok: Boolean(result?.ok),
-            driver: driver.driver,
-            messageId: typeof result?.messageId === 'string' ? result.messageId : undefined,
-        };
-    }
-    if (driver.driver === 'sendgrid' || driver.driver === 'mailgun' || driver.driver === 'smtp') {
-        throw ErrorFactory.createConfigError(`Mail driver not registered: ${driver.driver} (run \`zin add mail:${driver.driver}\` / \`npm i @zintrust/mail-${driver.driver}\`)`);
-    }
-    // Config exists for future drivers, but implementations are intentionally CLI/runtime-safe and added incrementally.
-    {
-        const err = ErrorFactory.createConfigError(`Mail driver not implemented: ${mailConfig.default}`);
-        throw err;
-    }
-};
-const createMailer = (name) => Object.freeze({
-    async send(input) {
-        const driver = mailConfig.getDriver(name);
-        if (driver.driver === 'disabled') {
-            const err = ErrorFactory.createConfigError('Mail driver is disabled (set MAIL_DRIVER)');
-            throw err;
-        }
-        const from = resolveFrom(input.from);
-        const storage = createStorageWrapper();
-        const attachments = await resolveAttachments(input.attachments, { storage });
-        return sendWithDriver(driver, {
-            to: input.to,
-            from,
-            subject: input.subject,
-            text: input.text,
-            html: input.html,
-            attachments,
-        });
-    },
-});
-export const Mail = Object.freeze({
-    /**
-     * Select a named mailer (key from mailConfig.drivers).
-     *
-     * Example: `Mail.mailer('transactional').send(...)`
-     */
-    mailer(name) {
-        return createMailer(name);
-    },
-    async send(input) {
-        return createMailer().send(input);
-    },
-});
-export default Mail;
+export { default, Mail } from './index.js';

package/src/tools/mail/drivers/SendGrid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SendGrid.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/drivers/SendGrid.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,UAAU,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,eAAO,MAAM,cAAc;iBACN,cAAc,WAAW,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;EAoE7E,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"SendGrid.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/drivers/SendGrid.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,UAAU,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAIF,eAAO,MAAM,cAAc;iBACN,cAAc,WAAW,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;EAoE7E,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/tools/mail/drivers/SendGrid.js

@@ -1,3 +1,4 @@
+import { MIME_TYPES } from '../../../config/constants.js';
 import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
 const normalizeRecipients = (to) => (Array.isArray(to) ? to : [to]);
 export const SendGridDriver = Object.freeze({
@@ -14,10 +15,10 @@ export const SendGridDriver = Object.freeze({
             },
         ];
         const content = [
-            { type: 'text/plain', value: message.text },
+            { type: MIME_TYPES.TEXT, value: message.text },
         ];
         if (typeof message.html === 'string' && message.html !== '') {
-            content.push({ type: 'text/html', value: message.html });
+            content.push({ type: MIME_TYPES.HTML, value: message.html });
         }
         const body = {
             personalizations,
@@ -38,7 +39,7 @@ export const SendGridDriver = Object.freeze({
             method: 'POST',
             headers: {
                 Authorization: `Bearer ${config.apiKey}`,
-                'content-type': 'application/json',
+                'content-type': MIME_TYPES.JSON,
             },
             body: JSON.stringify(body),
         });

package/src/tools/mail/drivers/Smtp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Smtp.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/drivers/Smtp.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA0XF,eAAO,MAAM,UAAU;IACrB;;;;OAIG;iBACgB,UAAU,WAAW,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;EAgDzE,CAAC;AAEH,eAAe,UAAU,CAAC"}
+{"version":3,"file":"Smtp.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/drivers/Smtp.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA+YF,eAAO,MAAM,UAAU;IACrB;;;;OAIG;iBACgB,UAAU,WAAW,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;EAgDzE,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/src/tools/mail/drivers/Smtp.js

@@ -78,7 +78,7 @@ const createLineReader = (socket) => {
             return undefined;
         const line = buffer.slice(0, idx + 1);
         buffer = buffer.slice(idx + 1);
-        return line.replaceAll(/\r?\n$/, '');
+        return line.replace(/\r?\n$/, '');
     };
     const readLine = async () => {
         const immediate = tryReadLineFromBuffer();
@@ -159,15 +159,37 @@ const doAuthLoginIfNeeded = async (socket, reader, config) => {
     if (username.trim() === '' || password.trim() === '') {
         throw ErrorFactory.createConfigError('SMTP: both MAIL_USERNAME and MAIL_PASSWORD are required');
     }
-    await writeLine(socket, 'AUTH LOGIN');
-    const auth1 = await reader.readResponse();
-    assertCode(auth1, 334, 'AUTH LOGIN');
-    await writeLine(socket, toBase64(username));
-    const auth2 = await reader.readResponse();
-    assertCode(auth2, 334, 'AUTH username');
-    await writeLine(socket, toBase64(password));
-    const auth3 = await reader.readResponse();
-    assertCode(auth3, 235, 'AUTH password');
+    // Try AUTH PLAIN first (more widely supported)
+    try {
+        // AUTH PLAIN format: base64("\0username\0password")
+        const authPlainString = `\0${username}\0${password}`;
+        const authPlainEncoded = toBase64(authPlainString);
+        await writeLine(socket, `AUTH PLAIN ${authPlainEncoded}`);
+        const authPlain = await reader.readResponse();
+        assertCode(authPlain, 235, 'AUTH PLAIN');
+        return; // Success!
+    }
+    catch (plainError) {
+        // AUTH PLAIN failed, try AUTH LOGIN as fallback
+        try {
+            await writeLine(socket, 'AUTH LOGIN');
+            const auth1 = await reader.readResponse();
+            assertCode(auth1, 334, 'AUTH LOGIN');
+            await writeLine(socket, toBase64(username));
+            const auth2 = await reader.readResponse();
+            assertCode(auth2, 334, 'AUTH username');
+            await writeLine(socket, toBase64(password));
+            const auth3 = await reader.readResponse();
+            assertCode(auth3, 235, 'AUTH password');
+        }
+        catch (loginError) {
+            // Both methods failed, throw the original error
+            throw ErrorFactory.createConnectionError('SMTP authentication failed', {
+                error: plainError,
+                loginError,
+            });
+        }
+    }
 };
 const doMailFrom = async (socket, reader, fromEmail) => {
     await writeLine(socket, `MAIL FROM:<${fromEmail}>`);

package/src/tools/mail/index.d.ts

@@ -0,0 +1,40 @@
+import { type AttachmentInput } from './attachments';
+export type SendMailInput = {
+    to: string | string[];
+    subject: string;
+    text: string;
+    html?: string;
+    from?: {
+        address?: string;
+        name?: string;
+    };
+    attachments?: AttachmentInput[];
+};
+export type SendMailResult = {
+    ok: boolean;
+    driver: 'sendgrid' | 'disabled' | 'smtp' | 'ses' | 'mailgun' | 'nodemailer';
+    messageId?: string;
+};
+export interface RenderMailInput {
+    template: string;
+    variables?: Record<string, unknown>;
+}
+export declare const Mail: Readonly<{
+    /**
+     * Render a template with variables and return HTML (preview only).
+     */
+    render(input: RenderMailInput): Promise<string>;
+    /** Alias of render */
+    view(input: RenderMailInput): Promise<string>;
+    /**
+     * Select a named mailer (key from mailConfig.drivers).
+     *
+     * Example: `Mail.mailer('transactional').send(...)`
+     */
+    mailer(name: string): Readonly<{
+        send: (input: SendMailInput) => Promise<SendMailResult>;
+    }>;
+    send(input: SendMailInput): Promise<SendMailResult>;
+}>;
+export default Mail;
+//# sourceMappingURL=index.d.ts.map

package/src/tools/mail/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI7E,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,YAAY,CAAC;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAoJF,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAcD,eAAO,MAAM,IAAI;IACf;;OAEG;kBACiB,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD,sBAAsB;gBACJ,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAGnD;;;;OAIG;iBACU,MAAM;cA5Db,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC;;gBAgErC,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC;EAGzD,CAAC;AAEH,eAAe,IAAI,CAAC"}

package/src/tools/mail/index.js

@@ -0,0 +1,129 @@
+import { mailConfig } from '../../config/mail.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { SesDriver } from './drivers/Ses.js';
+import { resolveAttachments } from './attachments.js';
+import { MailDriverRegistry } from './MailDriverRegistry.js';
+import { Storage } from '../storage/index.js';
+const resolveFrom = (input) => {
+    const address = input?.address ?? mailConfig.from.address;
+    const name = input?.name ?? mailConfig.from.name;
+    if (address.trim() === '') {
+        const err = ErrorFactory.createConfigError('Mail: missing from address (set MAIL_FROM_ADDRESS or pass from.address)');
+        throw err;
+    }
+    return { email: address, name: name.trim() === '' ? undefined : name };
+};
+function assertStorageDiskLike(value) {
+    if (typeof value !== 'object' || value === null) {
+        const err = ErrorFactory.createConfigError('Storage disk is invalid (expected object)');
+        throw err;
+    }
+    const v = value;
+    const driver = v['driver'];
+    if (typeof driver !== 'object' || driver === null) {
+        const err = ErrorFactory.createConfigError('Storage disk driver is invalid (expected object)');
+        throw err;
+    }
+    const d = driver;
+    if (typeof d['get'] !== 'function') {
+        const err = ErrorFactory.createConfigError('Storage disk driver is missing get()');
+        throw err;
+    }
+    if (typeof d['exists'] !== 'function') {
+        const err = ErrorFactory.createConfigError('Storage disk driver is missing exists()');
+        throw err;
+    }
+}
+const getDiskSafe = (disk) => {
+    const diskValue = Storage.getDisk(disk);
+    assertStorageDiskLike(diskValue);
+    return diskValue;
+};
+const createStorageWrapper = () => ({
+    async get(disk, path) {
+        const d = getDiskSafe(disk);
+        const result = await Promise.resolve(d.driver.get(d.config, path));
+        return result;
+    },
+    async exists(disk, path) {
+        const d = getDiskSafe(disk);
+        const result = await Promise.resolve(d.driver.exists(d.config, path));
+        return Boolean(result);
+    },
+});
+const sendWithDriver = async (driver, message) => {
+    if (driver.driver === 'ses') {
+        const result = await SesDriver.send({ region: driver.region }, message);
+        return { ok: result.ok, driver: 'ses', messageId: result.messageId };
+    }
+    // Drivers resolve via MailDriverRegistry (external packages)
+    const external = MailDriverRegistry.get(driver.driver);
+    if (external !== undefined) {
+        const result = await external(driver, message);
+        return {
+            ok: Boolean(result?.ok),
+            driver: driver.driver,
+            messageId: typeof result?.messageId === 'string' ? result.messageId : undefined,
+        };
+    }
+    if (driver.driver === 'sendgrid' || driver.driver === 'mailgun' || driver.driver === 'smtp') {
+        throw ErrorFactory.createConfigError(`Mail driver not registered: ${driver.driver} (run \`zin add mail:${driver.driver}\` / \`npm i @zintrust/mail-${driver.driver}\`)`);
+    }
+    // Config exists for future drivers, but implementations are intentionally CLI/runtime-safe and added incrementally.
+    {
+        const err = ErrorFactory.createConfigError(`Mail driver not implemented: ${mailConfig.default}`);
+        throw err;
+    }
+};
+const createMailer = (name) => Object.freeze({
+    async send(input) {
+        const driver = mailConfig.getDriver(name);
+        if (driver.driver === 'disabled') {
+            const err = ErrorFactory.createConfigError('Mail driver is disabled (set MAIL_DRIVER)');
+            throw err;
+        }
+        const from = resolveFrom(input.from);
+        const storage = createStorageWrapper();
+        const attachments = await resolveAttachments(input.attachments, { storage });
+        return sendWithDriver(driver, {
+            to: input.to,
+            from,
+            subject: input.subject,
+            text: input.text,
+            html: input.html,
+            attachments,
+        });
+    },
+});
+async function renderTemplateToHtml(input) {
+    const { template, variables } = input;
+    // Import lazily to avoid circular deps
+    const { loadTemplate } = await import('./template-loader.js');
+    // template-loader expects full filename
+    const fileName = template.endsWith('.html') ? template : `${template}.html`;
+    return loadTemplate(fileName, (variables ?? {}));
+}
+export const Mail = Object.freeze({
+    /**
+     * Render a template with variables and return HTML (preview only).
+     */
+    async render(input) {
+        return renderTemplateToHtml(input);
+    },
+    /** Alias of render */
+    async view(input) {
+        return renderTemplateToHtml(input);
+    },
+    /**
+     * Select a named mailer (key from mailConfig.drivers).
+     *
+     * Example: `Mail.mailer('transactional').send(...)`
+     */
+    mailer(name) {
+        return createMailer(name);
+    },
+    async send(input) {
+        return createMailer().send(input);
+    },
+});
+export default Mail;

package/src/tools/mail/template-loader.d.ts

@@ -0,0 +1,10 @@
+import type { TemplateVariables } from './template-utils';
+/**
+ * Load and render email template with variable substitution
+ */
+export declare function loadTemplate(templateName: string, variables?: TemplateVariables): Promise<string>;
+/**
+ * Get list of available templates
+ */
+export declare function getAvailableTemplates(): string[];
+//# sourceMappingURL=template-loader.d.ts.map

package/src/tools/mail/template-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-loader.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/template-loader.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9D;;GAEG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,iBAAsB,GAChC,OAAO,CAAC,MAAM,CAAC,CA6CjB;AAuDD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAShD"}

package/src/tools/mail/template-loader.js

@@ -0,0 +1,101 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { readFile } from '../../node-singletons/fs.js';
+import { dirname, join } from '../../node-singletons/path.js';
+import { fileURLToPath } from '../../node-singletons/url.js';
+import { Env } from '../../config/env.js';
+import { interpolate } from './template-utils.js';
+/**
+ * Load and render email template with variable substitution
+ */
+export async function loadTemplate(templateName, variables = {}) {
+    try {
+        const baseDir = dirname(fileURLToPath(import.meta.url));
+        const isPath = templateName.includes('/') || templateName.endsWith('.html');
+        let templatePath;
+        if (isPath) {
+            if (templateName.startsWith('/')) {
+                templatePath = templateName;
+            }
+            else {
+                templatePath = join(process.cwd(), templateName);
+            }
+        }
+        else {
+            templatePath = join(baseDir, 'templates', `${templateName}.html`);
+        }
+        let template;
+        try {
+            template = await readFile(templatePath, 'utf-8');
+        }
+        catch {
+            // Fallback to built-in directory if the supplied name looked like a file but wasn't found
+            const fallbackPath = join(baseDir, 'templates', templateName.endsWith('.html') ? templateName : `${templateName}.html`);
+            template = await readFile(fallbackPath, 'utf-8');
+        }
+        // Replace variables using shared interpolate util
+        const mergedVars = {
+            year: new Date().getFullYear().toString(),
+            APP_NAME: Env.APP_NAME ?? 'ZinTrust',
+            ...variables,
+        };
+        let rendered = interpolate(template, mergedVars);
+        // Handle conditional blocks {{#if_condition}}...{{/if_condition}}
+        rendered = renderConditionals(rendered, variables);
+        // Handle loops {{#each_array}}...{{/each_array}}
+        rendered = renderLoops(rendered, variables);
+        return rendered;
+    }
+    catch (error) {
+        throw ErrorFactory.createConfigError(`Failed to load template ${templateName}: ${error}`);
+    }
+}
+/**
+ * Render conditional blocks {{#if_condition}}...{{/if_condition}}
+ */
+function renderConditionals(template, variables) {
+    const conditionalRegex = /{{#if_(\w+)}}(.+?){{\/if_\1}}/gs;
+    return template.replaceAll(conditionalRegex, (_fullMatch, condition, content) => {
+        const value = variables[condition];
+        if (value === true || value === 'true') {
+            return content;
+        }
+        return '';
+    });
+}
+/**
+ * Render loop blocks {{#each_array}}...{{/each_array}}
+ */
+function renderLoops(template, variables) {
+    const loopRegex = /{{#each_(\w+)}}(.+?){{\/each_\1}}/gs;
+    return template.replaceAll(loopRegex, (_fullMatch, arrayName, content) => {
+        const array = variables[arrayName];
+        if (!Array.isArray(array)) {
+            return '';
+        }
+        return array
+            .map((item) => {
+            let rendered = content;
+            if (typeof item === 'object' && item !== null) {
+                for (const [key, value] of Object.entries(item)) {
+                    const regex = new RegExp(`{{${key}}}`, 'g');
+                    rendered = rendered.replaceAll(regex, String(value ?? ''));
+                }
+            }
+            return rendered;
+        })
+            .join('');
+    });
+}
+/**
+ * Get list of available templates
+ */
+export function getAvailableTemplates() {
+    return [
+        'welcome.html',
+        'password-reset.html',
+        'job-completed.html',
+        'worker-alert.html',
+        'performance-report.html',
+        'general.html',
+    ];
+}

package/src/tools/mail/template-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Template utilities shared by mail modules.
+ */
+export type TemplateVariables = Record<string, unknown>;
+/**
+ * Simple handlebars‐style interpolation: replaces all occurrences of
+ * `{{ key }}` (whitespace optional) with String(value).
+ */
+export declare function interpolate(template: string, data: TemplateVariables): string;
+//# sourceMappingURL=template-utils.d.ts.map

package/src/tools/mail/template-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-utils.d.ts","sourceRoot":"","sources":["../../../../src/tools/mail/template-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAQ7E"}

package/src/tools/mail/template-utils.js

@@ -0,0 +1,16 @@
+/**
+ * Template utilities shared by mail modules.
+ */
+/**
+ * Simple handlebars‐style interpolation: replaces all occurrences of
+ * `{{ key }}` (whitespace optional) with String(value).
+ */
+export function interpolate(template, data) {
+    let out = template;
+    for (const [key, value] of Object.entries(data)) {
+        const replacement = value === null || value === undefined ? '' : String(value);
+        const regex = new RegExp(String.raw `{{\s*${key}\s*}}`, 'g');
+        out = out.replace(regex, replacement);
+    }
+    return out;
+}

package/src/tools/mail/templates/index.d.ts

@@ -24,4 +24,34 @@ export declare const MailTemplates: Readonly<{
         }>;
     }>;
 }>;
+export interface MarkdownTemplateMetadata {
+    subject?: string;
+    preheader?: string;
+    variables?: string[];
+    content: string;
+}
+export interface MarkdownRenderResult {
+    html: string;
+    meta: {
+        subject?: string;
+        content: string;
+        variables?: string[];
+    };
+}
+/**
+ * List all available HTML mail templates.
+ * Returns template names without the .html extension.
+ */
+export declare function listTemplates(): string[];
+/**
+ * Load a mail template by name.
+ * Note: HTML templates don't have embedded metadata like markdown templates did.
+ * This function returns the raw HTML content.
+ */
+export declare function loadTemplate(name: string): MarkdownTemplateMetadata;
+/**
+ * Render a mail template with variables.
+ * Note: This is a compatibility function. For production use, use MailTemplateRenderer instead.
+ */
+export declare function renderTemplate(name: string, variables?: Record<string, unknown>): MarkdownRenderResult;
 //# sourceMappingURL=index.d.ts.map

package/src/tools/mail/templates/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/templates/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAW3D,eAAO,MAAM,oBAAoB;6BATD,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM;qBAY3D,YAAY,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;EAO3E,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;EASO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/tools/mail/templates/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAW3D,eAAO,MAAM,oBAAoB;6BATD,MAAM,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM;qBAY3D,YAAY,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY;EAO3E,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;EASO,CAAC;AAYlC,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE;QACJ,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAWxC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,wBAAwB,CAiBnE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC,oBAAoB,CAoBtB"}