ztechno_core 0.0.64 → 0.0.66

package/lib/crypto_service.d.ts

@@ -1,4 +1,4 @@
-import { HashStruct } from './typings/crypto_types';
+import { HashStruct } from './typings';
 export declare class ZCryptoService {
   static encrypt(text: string): HashStruct;
   static decrypt(data: HashStruct): string;

package/lib/engine_base.d.ts

@@ -1,10 +1,10 @@
 import { ZMailService } from './mail_service';
-import { ZSqlService } from './sql_service';
+import { ZSQLService } from './sql_service';
 import { ZTranslateService } from './translate_service';
 import { ZUserService } from './user_service';
 export declare class ZEngineBase {
   static mailService?: ZMailService;
-  static sqlService?: ZSqlService;
+  static sqlService?: ZSQLService;
   static translateService?: ZTranslateService;
   static userService?: ZUserService;
   protected static start(): any;

package/lib/index.d.ts

@@ -1,19 +1,9 @@
 import { ZEngineBase } from './engine_base';
 import { ZCryptoService } from './crypto_service';
 import { ZMailService } from './mail_service';
-import { ZSqlService } from './sql_service';
+import { ZSQLService } from './sql_service';
 import { ZTranslateService } from './translate_service';
 import { ZUserService } from './user_service';
 export { middleware } from './express';
-export { HashStruct } from './typings/crypto_types';
-export {
-  MailOptions,
-  MailOptionsBase,
-  MailOptionsHtml,
-  MailOptionsText,
-  MailServiceOptions,
-  MailResponse,
-} from './typings/mail_types';
-export { TranslateData, Dom as ZDom, Node as ZNode, ZNodeText, dbTranslationRow } from './typings/translate_types';
-export { ZRequiredUserColumns, ZUser, ZUserCredentials, ZUserSession } from './typings/user_types';
-export { ZCryptoService, ZMailService, ZSqlService, ZTranslateService, ZUserService, ZEngineBase };
+export * from './typings';
+export { ZEngineBase, ZCryptoService, ZMailService, ZSQLService as ZSqlService, ZTranslateService, ZUserService };

package/lib/index.js

@@ -1,13 +1,40 @@
 'use strict';
+var __createBinding =
+  (this && this.__createBinding) ||
+  (Object.create
+    ? function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        var desc = Object.getOwnPropertyDescriptor(m, k);
+        if (!desc || ('get' in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+          desc = {
+            enumerable: true,
+            get: function () {
+              return m[k];
+            },
+          };
+        }
+        Object.defineProperty(o, k2, desc);
+      }
+    : function (o, m, k, k2) {
+        if (k2 === undefined) k2 = k;
+        o[k2] = m[k];
+      });
+var __exportStar =
+  (this && this.__exportStar) ||
+  function (m, exports) {
+    for (var p in m)
+      if (p !== 'default' && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+  };
 Object.defineProperty(exports, '__esModule', { value: true });
-exports.ZEngineBase =
-  exports.ZUserService =
+exports.ZUserService =
   exports.ZTranslateService =
   exports.ZSqlService =
   exports.ZMailService =
   exports.ZCryptoService =
+  exports.ZEngineBase =
   exports.middleware =
     void 0;
+// Core services
 const engine_base_1 = require('./engine_base');
 Object.defineProperty(exports, 'ZEngineBase', {
   enumerable: true,
@@ -33,7 +60,7 @@ const sql_service_1 = require('./sql_service');
 Object.defineProperty(exports, 'ZSqlService', {
   enumerable: true,
   get: function () {
-    return sql_service_1.ZSqlService;
+    return sql_service_1.ZSQLService;
   },
 });
 const translate_service_1 = require('./translate_service');
@@ -50,6 +77,7 @@ Object.defineProperty(exports, 'ZUserService', {
     return user_service_1.ZUserService;
   },
 });
+// Express middleware
 var express_1 = require('./express');
 Object.defineProperty(exports, 'middleware', {
   enumerable: true,
@@ -57,3 +85,5 @@ Object.defineProperty(exports, 'middleware', {
     return express_1.middleware;
   },
 });
+// Re-export all types from typings barrel
+__exportStar(require('./typings'), exports);

package/lib/mail_service.d.ts

@@ -1,8 +1,77 @@
-import { MailOptions, MailOptionsHtml, MailOptionsText, MailResponse, MailServiceOptions } from './typings/mail_types';
+import {
+  MailOptions,
+  MailOptionsHtml,
+  MailOptionsText,
+  MailResponse,
+  MailServiceOptions,
+  ZMailSendOptTemplate,
+} from './typings';
+import { ZMailBlacklistOrm } from './orm/mail_blacklist_orm';
 export declare class ZMailService {
   private opt;
-  protected get sql(): import('./sql_service').ZSqlService;
+  protected get sql(): import('./sql_service').ZSQLService;
+  protected blacklistOrm: ZMailBlacklistOrm;
+  /**
+   * Creates a new ZMailService instance
+   * @param opt - Configuration options for the mail service including authentication, sender email, and SQL service
+   */
   constructor(opt: MailServiceOptions);
+  /**
+   * Checks if an email is allowed to be sent by verifying it's not blacklisted
+   * @param mailOpts - Mail options containing the recipient email to check
+   * @returns Promise that resolves to true if email is allowed, false if blacklisted
+   * @protected
+   */
   protected allowSend(mailOpts: MailOptions): Promise<boolean>;
-  send(mailOpts: MailOptionsText | MailOptionsHtml): Promise<MailResponse | undefined>;
+  /**
+   * Sends an email with text content
+   * @param mailOpts - Mail options with text body
+   * @returns Promise that resolves to mail response or undefined if sending is not allowed
+   */
+  send(mailOpts: MailOptionsText): Promise<MailResponse | undefined>;
+  /**
+   * Sends an email with HTML content
+   * @param mailOpts - Mail options with HTML body
+   * @returns Promise that resolves to mail response or undefined if sending is not allowed
+   */
+  send(mailOpts: MailOptionsHtml): Promise<MailResponse | undefined>;
+  /**
+   * Sends an advanced email with text content, supporting templates and variable injection
+   * @param mailOpts - Mail options with text body
+   * @returns Promise that resolves to mail response
+   */
+  sendAdvanced(mailOpts: MailOptionsText): Promise<any>;
+  /**
+   * Sends an advanced email with HTML content, supporting templates and variable injection
+   * @param mailOpts - Mail options with HTML body
+   * @returns Promise that resolves to mail response
+   */
+  sendAdvanced(mailOpts: MailOptionsHtml): Promise<any>;
+  /**
+   * Sends an advanced email using a template file, supporting variable injection
+   * @param mailOpts - Mail options with template path and injection variables
+   * @returns Promise that resolves to mail response
+   */
+  sendAdvanced(mailOpts: ZMailSendOptTemplate): Promise<any>;
+  /**
+   * Fetches the content of a template file from the filesystem
+   * @param template - Path to the template file to read
+   * @returns Promise that resolves to the template content as a string
+   * @throws Will throw an error if the file cannot be read
+   * @private
+   */
+  private fetchTemplate;
+  /**
+   * Injects variables into a body string by replacing placeholder tokens
+   * @param body - The string content where variables should be injected
+   * @param inject - Object containing key-value pairs where keys are variable names and values are replacement content
+   * @returns Promise that resolves to the body string with all variables injected
+   * @example
+   * ```typescript
+   * const result = await inject('Hello :name from :company', { name: 'John', company: 'ACME' });
+   * // Returns: 'Hello John from ACME'
+   * ```
+   * @private
+   */
+  private inject;
 }

package/lib/mail_service.js

@@ -7,16 +7,38 @@ var __importDefault =
 Object.defineProperty(exports, '__esModule', { value: true });
 exports.ZMailService = void 0;
 const nodemailer_1 = __importDefault(require('nodemailer'));
+const promises_1 = __importDefault(require('fs/promises'));
+const mail_blacklist_orm_1 = require('./orm/mail_blacklist_orm');
 class ZMailService {
   get sql() {
     return this.opt.sqlService;
   }
+  /**
+   * Creates a new ZMailService instance
+   * @param opt - Configuration options for the mail service including authentication, sender email, and SQL service
+   */
   constructor(opt) {
     this.opt = opt;
+    this.blacklistOrm = new mail_blacklist_orm_1.ZMailBlacklistOrm(opt);
   }
+  /**
+   * Checks if an email is allowed to be sent by verifying it's not blacklisted
+   * @param mailOpts - Mail options containing the recipient email to check
+   * @returns Promise that resolves to true if email is allowed, false if blacklisted
+   * @protected
+   */
   async allowSend(mailOpts) {
+    const blacklistEntry = await this.blacklistOrm.findOne({ email: mailOpts.recipient, is_blacklisted: 1 });
+    if (blacklistEntry) {
+      return false;
+    }
     return true;
   }
+  /**
+   * Sends an email with either text or HTML content
+   * @param mailOpts - Mail options containing recipient, subject, and body/html content
+   * @returns Promise that resolves to mail response or undefined if sending is not allowed
+   */
   async send(mailOpts) {
     const allow = await this.allowSend(mailOpts);
     if (!allow) {
@@ -41,5 +63,64 @@ class ZMailService {
       });
     });
   }
+  /**
+   * Sends an advanced email with enhanced features including template loading and variable injection.
+   * Automatically generates unsubscribe hash and injects common variables like email and hashToUnsubscribe.
+   * @param mailOpts - Mail options that can include template path, injection variables, and standard mail fields
+   * @returns Promise that resolves to mail response from the underlying send method
+   * @example
+   * ```typescript
+   * await mailService.sendAdvanced({
+   *   recipient: 'user@example.com',
+   *   subject: 'Welcome!',
+   *   template: './templates/welcome.html',
+   *   inject: { name: 'John', company: 'ACME Corp' }
+   * });
+   * ```
+   */
+  async sendAdvanced(mailOpts) {
+    const opts = mailOpts;
+    const hashToUnsubscribe = await this.blacklistOrm.genEmailUnsubscribeHash({ email: mailOpts.recipient });
+    if (opts.template !== undefined) {
+      opts.html = await this.fetchTemplate(opts.template);
+    }
+    if (opts.inject !== undefined) {
+      const key = opts.html !== undefined ? 'html' : 'body';
+      const baseInject = { email: mailOpts.recipient, hashToUnsubscribe };
+      opts[key] = await this.inject(opts[key], Object.assign(baseInject, opts.inject));
+    }
+    return await this.send(opts);
+  }
+  /**
+   * Fetches the content of a template file from the filesystem
+   * @param template - Path to the template file to read
+   * @returns Promise that resolves to the template content as a string
+   * @throws Will throw an error if the file cannot be read
+   * @private
+   */
+  async fetchTemplate(template) {
+    return await promises_1.default.readFile(template, { encoding: 'utf-8' });
+  }
+  /**
+   * Injects variables into a body string by replacing placeholder tokens
+   * @param body - The string content where variables should be injected
+   * @param inject - Object containing key-value pairs where keys are variable names and values are replacement content
+   * @returns Promise that resolves to the body string with all variables injected
+   * @example
+   * ```typescript
+   * const result = await inject('Hello :name from :company', { name: 'John', company: 'ACME' });
+   * // Returns: 'Hello John from ACME'
+   * ```
+   * @private
+   */
+  async inject(body, inject) {
+    Object.keys(inject ?? {}).map((variableName) => {
+      const key = `:${variableName}`;
+      while (body.indexOf(key) !== -1) {
+        body = body.replace(key, inject[variableName].toString());
+      }
+    });
+    return body;
+  }
 }
 exports.ZMailService = ZMailService;

package/lib/orm/mail_blacklist_orm.d.ts

@@ -0,0 +1,21 @@
+import { ZOrm } from './orm';
+import { ZSQLService } from '../sql_service';
+import { ZMailBlacklist, ZMailBlacklistSearch } from '../typings';
+export declare class ZMailBlacklistOrm extends ZOrm {
+  private hashSalt;
+  private sqlService;
+  constructor(opt: { alias?: string; sqlService: ZSQLService; hashSalt?: string });
+  genEmailUnsubscribeHash({ email }: { email: string }): Promise<string>;
+  create(
+    item: Omit<ZMailBlacklist, 'updated_at' | 'created_at'>,
+  ): Promise<Omit<ZMailBlacklist, 'updated_at' | 'created_at'>>;
+  findOne(conditions: Partial<ZMailBlacklist>): Promise<ZMailBlacklist>;
+  findAll(
+    conditions?: Partial<ZMailBlacklistSearch>,
+    opt?: {
+      limit?: number;
+    },
+  ): Promise<ZMailBlacklist[]>;
+  update({ email, is_blacklisted }: Pick<ZMailBlacklist, 'email' | 'is_blacklisted'>): Promise<boolean>;
+  createTable(): Promise<void>;
+}

package/lib/orm/mail_blacklist_orm.js

@@ -0,0 +1,68 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.ZMailBlacklistOrm = void 0;
+const orm_1 = require('./orm');
+const crypto_service_1 = require('../crypto_service');
+class ZMailBlacklistOrm extends orm_1.ZOrm {
+  constructor(opt) {
+    super({ alias: opt.alias ?? 'email_blacklist' });
+    this.sqlService = opt.sqlService;
+    this.hashSalt = opt.hashSalt ?? 'ZTECHNO';
+  }
+  async genEmailUnsubscribeHash({ email }) {
+    const existingHash = await this.findOne({ email });
+    if (existingHash !== undefined) {
+      return existingHash.hash;
+    }
+    const hash = crypto_service_1.ZCryptoService.hash('sha512', `${this.hashSalt}-${email}`);
+    await this.create({ email, hash, is_blacklisted: 0 });
+    return hash;
+  }
+  async create(item) {
+    const res = await this.sqlService.query(
+      `
+      INSERT INTO \`${this.alias}\` (email, hash, is_blacklisted, updated_at, created_at)
+      VALUES (:email, :hash, :is_blacklisted, NOW(), NOW())
+      ON DUPLICATE KEY UPDATE hash=:hash, updated_at=NOW()
+    `,
+      item,
+    );
+    return item; // return Object.assign(item, { invoice_id: res.insertId }) as ZMailBlacklist
+  }
+  async findOne(conditions) {
+    const rows = await this.findAll(conditions, { limit: 1 });
+    return rows[0];
+  }
+  async findAll(conditions, opt) {
+    const whereKeys = Object.keys(conditions ?? {});
+    const whereClause = whereKeys.length ? `WHERE ${whereKeys.map((key) => `${key}=:${key}`).join(' AND ')}` : '';
+    const limit = opt?.limit ? `LIMIT ${opt.limit}` : '';
+    return await this.sqlService.exec({
+      query: /*SQL*/ `SELECT * FROM \`${this.alias}\` ${whereClause} ${limit}`,
+      params: conditions,
+    });
+  }
+  async update({ email, is_blacklisted }) {
+    const res = await this.sqlService.query(
+      `
+      UPDATE \`${this.alias}\` SET is_blacklisted=:is_blacklisted, updated_at=NOW() WHERE email=:email
+    `,
+      { email, is_blacklisted },
+    );
+    return res.affectedRows !== 0;
+  }
+  async createTable() {
+    await this.sqlService.query(/*SQL*/ `
+      CREATE TABLE \`${this.alias}\` (
+        \`email\` varchar(512) NOT NULL,
+        \`hash\` varchar(256) NOT NULL,
+        \`is_blacklisted\` tinyint(1) NOT NULL DEFAULT 0,
+        \`updated_at\` datetime NOT NULL DEFAULT current_timestamp(),
+        \`created_at\` datetime NOT NULL DEFAULT current_timestamp(),
+        PRIMARY KEY (\`email\`),
+        KEY \`is_blacklisted\` (\`is_blacklisted\`)
+      ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+    `);
+  }
+}
+exports.ZMailBlacklistOrm = ZMailBlacklistOrm;

package/lib/orm/orm.d.ts

@@ -0,0 +1,8 @@
+import { ZSQLService } from '../sql_service';
+export declare class ZOrm {
+  readonly alias: string;
+  constructor(opt: { alias: string });
+  ensureTableExists(sqlService: ZSQLService): Promise<void>;
+  private checkTableExists;
+  createTable(sqlService: ZSQLService): Promise<void>;
+}

package/lib/orm/orm.js

@@ -0,0 +1,26 @@
+'use strict';
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.ZOrm = void 0;
+class ZOrm {
+  constructor(opt) {
+    this.alias = opt.alias;
+  }
+  async ensureTableExists(sqlService) {
+    const exists = await this.checkTableExists(sqlService);
+    if (!exists) {
+      await this.createTable(sqlService);
+    }
+  }
+  async checkTableExists(sqlService) {
+    const res = await sqlService.query(`
+      SELECT ENGINE, VERSION, CREATE_TIME FROM information_schema.tables
+      WHERE table_schema = '${sqlService.database}' AND table_name = '${this.alias}'
+      LIMIT 1
+    `);
+    return res.length > 0;
+  }
+  async createTable(sqlService) {
+    throw new Error(`${this.alias} Create Table Statement Not Implemented!`);
+  }
+}
+exports.ZOrm = ZOrm;

package/lib/sql_service.d.ts

@@ -1,7 +1,7 @@
 import * as mysql from 'mysql';
 type ZOnErrorCallback = (err: mysql.MysqlError) => any;
 type ZOnLogCallback = (log: string) => any;
-export declare class ZSqlService {
+export declare class ZSQLService {
   private options;
   private pool;
   private defaultPoolconfig;

package/lib/sql_service.js

@@ -40,9 +40,9 @@ var __importStar =
     return result;
   };
 Object.defineProperty(exports, '__esModule', { value: true });
-exports.ZSqlService = void 0;
+exports.ZSQLService = void 0;
 const mysql = __importStar(require('mysql'));
-class ZSqlService {
+class ZSQLService {
   get database() {
     return this.databaseName;
   }
@@ -149,4 +149,4 @@ class ZSqlService {
     return false;
   }
 }
-exports.ZSqlService = ZSqlService;
+exports.ZSQLService = ZSQLService;

package/lib/translate_service.d.ts

@@ -1,17 +1,23 @@
-import { TranslateData, dbTranslationRow } from './index';
-import { ATranslateLang, TranslateServiceOptions } from './typings/translate_types';
+import { TranslateData, dbTranslationRow, ATranslateLang, TranslateServiceOptions } from './typings';
 export declare class ZTranslateService {
   private opt;
   private localCache;
   private get sql();
   surpressErrors: boolean;
+  private maxRetries;
+  private retryDelay;
+  private fallbackText;
   getLanguages(): ATranslateLang[];
   getSourceLang(): string;
   getDefaultLang(): string;
   constructor(opt: TranslateServiceOptions);
   private codes;
   getLang(cookies: { [key: string]: string }): string;
+  private sleep;
+  private logError;
+  private retryOperation;
   translateText(langOrReq: string | any, text: string): Promise<string>;
+  private processHtmlEntities;
   translateHtml(
     html: string,
     cookies: {