@serve.zone/platformclient 1.1.4 → 1.2.0

package/ts/email/classes.emailconnector.ts

@@ -3,6 +3,80 @@ import * as plugins from '../plugins.js';
 
 import { logger } from '../logger.js';
 
+export type TServiceMailTlsMode = 'plain' | 'starttls' | 'implicitTls';
+
+export interface IServiceMailSmtpCredentials {
+  from: string;
+  host: string;
+  port: number;
+  tlsMode: TServiceMailTlsMode;
+  username: string;
+  password: string;
+  addressToken?: string;
+}
+
+export interface IServiceMailStatus {
+  ready: boolean;
+  from?: string;
+  host?: string;
+  port?: number;
+  tlsMode?: TServiceMailTlsMode;
+  usernameConfigured: boolean;
+  passwordConfigured: boolean;
+  missing: string[];
+}
+
+export interface IServiceMailAttachment {
+  filename: string;
+  contentType?: string;
+  content: string | Uint8Array;
+}
+
+export interface IServiceMailSendOptions {
+  from?: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  headers?: Record<string, string>;
+  attachments?: IServiceMailAttachment[];
+}
+
+export interface IServiceMailSendResult {
+  messageId?: string;
+  accepted?: string[];
+  rejected?: string[];
+  response?: string;
+}
+
+export interface IServiceMailInboundMessage extends plugins.servezoneInterfaces.data.IMailInboundMessagePayload {
+  from: string;
+  to: string[];
+  receivedAtIso: string;
+}
+
+export interface IServiceMailInboundHandlerResult {
+  accepted?: boolean;
+  workAppMessageId?: string;
+  message?: string;
+}
+
+export type IServiceMailInboundHandleResult =
+  plugins.servezoneInterfaces.requests.mail.IReq_DeliverInboundMail['response'];
+
+interface INodemailerSendResult {
+  messageId?: string;
+  accepted?: unknown[];
+  rejected?: unknown[];
+  response?: string;
+}
+
+export type TServiceMailInboundHandler = (
+  messageArg: IServiceMailInboundMessage,
+) => Promise<IServiceMailInboundHandlerResult | void> | IServiceMailInboundHandlerResult | void;
+
 export class SzEmailConnector {
   public platformClientRef: SzPlatformClient;
 
@@ -10,6 +84,9 @@ export class SzEmailConnector {
     this.platformClientRef = platformClientRefArg;
   }
 
+  /**
+   * Legacy platform-service email path. New service-mail code should use sendMail().
+   */
   public async sendEmail(
     optionsArg: plugins.servezoneInterfaces.platform.email.IReq_SendEmail['request']
   ) {
@@ -30,10 +107,255 @@ export class SzEmailConnector {
         'sendEmail'
       );
     const response = await typedRequest.fire(optionsArg);
+    return response.responseId;
+  }
+
+  public async getServiceMailStatus(addressArg?: string): Promise<IServiceMailStatus> {
+    const requestedAddress = addressArg?.trim().toLowerCase();
+    const token = requestedAddress ? this.getMailEnvToken(requestedAddress) : undefined;
+    const scopedEnv = token ? await this.readMailEnv(token) : undefined;
+    const defaultEnv = token ? await this.readMailEnv() : undefined;
+    const useDefaultEnv = requestedAddress
+      && !this.hasAnyMailEnvValue(scopedEnv)
+      && defaultEnv?.from?.trim().toLowerCase() === requestedAddress;
+    const env = useDefaultEnv ? defaultEnv! : scopedEnv || await this.readMailEnv();
+    const missingPrefix = useDefaultEnv || !token ? undefined : token;
+    const port = env.smtpPort ? Number(env.smtpPort) : undefined;
+    const tlsMode = this.normalizeTlsMode(env.smtpTlsMode || 'starttls');
+    const missing: string[] = [];
+    if (!env.from) missing.push(missingPrefix ? `MAIL_${missingPrefix}_FROM` : 'MAIL_FROM');
+    if (!env.smtpHost) missing.push(missingPrefix ? `MAIL_${missingPrefix}_SMTP_HOST` : 'SMTP_HOST');
+    if (!env.smtpPort || !Number.isInteger(port) || port! < 1 || port! > 65535) {
+      missing.push(missingPrefix ? `MAIL_${missingPrefix}_SMTP_PORT` : 'SMTP_PORT');
+    }
+    if (!env.smtpUsername) missing.push(missingPrefix ? `MAIL_${missingPrefix}_SMTP_USERNAME` : 'SMTP_USERNAME');
+    if (!env.smtpPassword) missing.push(missingPrefix ? `MAIL_${missingPrefix}_SMTP_PASSWORD` : 'SMTP_PASSWORD');
+    return {
+      ready: missing.length === 0,
+      from: env.from,
+      host: env.smtpHost,
+      port,
+      tlsMode,
+      usernameConfigured: Boolean(env.smtpUsername),
+      passwordConfigured: Boolean(env.smtpPassword),
+      missing,
+    };
+  }
+
+  public async getServiceMailCredentials(addressArg?: string): Promise<IServiceMailSmtpCredentials> {
+    const requestedAddress = addressArg?.trim().toLowerCase();
+    const requestedToken = requestedAddress ? this.getMailEnvToken(requestedAddress) : undefined;
+    const scopedEnv = requestedToken ? await this.readMailEnv(requestedToken) : undefined;
+    const hasScopedConfig = scopedEnv && Object.values(scopedEnv).some(Boolean);
+    const env = hasScopedConfig ? scopedEnv! : await this.readMailEnv();
+    const from = env.from?.trim().toLowerCase();
+    if (!from) throw new Error('MAIL_FROM is required for service mail');
+    if (requestedAddress && from !== requestedAddress) {
+      throw new Error(`No service mail credentials are configured for ${requestedAddress}`);
+    }
+    const port = Number(env.smtpPort);
+    if (!env.smtpHost) throw new Error('SMTP_HOST is required for service mail');
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      throw new Error('SMTP_PORT must be an integer between 1 and 65535');
+    }
+    if (!env.smtpUsername) throw new Error('SMTP_USERNAME is required for service mail');
+    if (!env.smtpPassword) throw new Error('SMTP_PASSWORD is required for service mail');
+    return {
+      from,
+      host: env.smtpHost,
+      port,
+      tlsMode: this.normalizeTlsMode(env.smtpTlsMode || 'starttls'),
+      username: env.smtpUsername,
+      password: env.smtpPassword,
+      addressToken: hasScopedConfig ? requestedToken : undefined,
+    };
+  }
+
+  public async sendText(optionsArg: Omit<IServiceMailSendOptions, 'html'> & { text: string }) {
+    return await this.sendMail(optionsArg);
+  }
+
+  public async sendHtml(optionsArg: Omit<IServiceMailSendOptions, 'text'> & { html: string }) {
+    return await this.sendMail(optionsArg);
+  }
+
+  public async sendMail(optionsArg: IServiceMailSendOptions): Promise<IServiceMailSendResult> {
+    if (!optionsArg.text && !optionsArg.html) {
+      throw new Error('Either text or html is required for service mail');
+    }
+    if (this.platformClientRef.debugMode) {
+      logger.log('info', `service mail debug send: ${optionsArg.subject} to ${this.listToArray(optionsArg.to).join(', ')}`);
+      return { messageId: 'debug' };
+    }
 
+    const credentials = await this.getServiceMailCredentials(optionsArg.from);
+    const smartsmtp = await plugins.getSmartsmtp();
+    const smtp = await smartsmtp.Smartsmtp.createSmartsmtpWithRelay({
+      smtpServer: credentials.host,
+      smtpPort: credentials.port,
+      smtpTlsMode: credentials.tlsMode,
+      smtpUser: credentials.username,
+      smtpPassword: credentials.password,
+    });
+    const result = (await smtp.nodemailerTransport.sendMail({
+      from: credentials.from,
+      to: this.listToArray(optionsArg.to),
+      cc: optionsArg.cc ? this.listToArray(optionsArg.cc) : undefined,
+      bcc: optionsArg.bcc ? this.listToArray(optionsArg.bcc) : undefined,
+      subject: optionsArg.subject,
+      text: optionsArg.text,
+      html: optionsArg.html,
+      headers: optionsArg.headers,
+      attachments: optionsArg.attachments?.map((attachmentArg) => ({
+        filename: attachmentArg.filename,
+        contentType: attachmentArg.contentType,
+        content: this.normalizeAttachmentContent(attachmentArg.content),
+      })),
+    })) as INodemailerSendResult;
+    return {
+      messageId: result.messageId,
+      accepted: Array.isArray(result.accepted) ? result.accepted.map(String) : undefined,
+      rejected: Array.isArray(result.rejected) ? result.rejected.map(String) : undefined,
+      response: result.response,
+    };
+  }
+
+  public normalizeInboundMessage(payloadArg: unknown): IServiceMailInboundMessage {
+    const payload = this.asRecord(payloadArg);
+    const deliveryCandidate = this.asRecord(payload.delivery || payload.message || payload);
+    const envelope = this.asRecord(deliveryCandidate.envelope);
+    const rawMessage = typeof deliveryCandidate.rawMessage === 'string' ? deliveryCandidate.rawMessage : '';
+    const rcptTo = Array.isArray(envelope.rcptTo) ? envelope.rcptTo.map(String) : [];
+    const receivedAt = typeof deliveryCandidate.receivedAt === 'number' ? deliveryCandidate.receivedAt : Date.now();
+    return {
+      spoolItemId: String(deliveryCandidate.spoolItemId || deliveryCandidate.id || ''),
+      owner: deliveryCandidate.owner as plugins.servezoneInterfaces.data.IMailResourceOwner | undefined,
+      envelope: {
+        mailFrom: String(envelope.mailFrom || deliveryCandidate.from || ''),
+        rcptTo,
+      },
+      rawMessage,
+      sizeBytes: typeof deliveryCandidate.sizeBytes === 'number' ? deliveryCandidate.sizeBytes : rawMessage.length,
+      messageId: deliveryCandidate.messageId ? String(deliveryCandidate.messageId) : undefined,
+      subject: deliveryCandidate.subject ? String(deliveryCandidate.subject) : this.extractHeader(rawMessage, 'subject'),
+      headers: this.normalizeHeaders(deliveryCandidate.headers),
+      source: deliveryCandidate.source as plugins.servezoneInterfaces.data.IMailConnectionInfo | undefined,
+      receivedAt,
+      from: String(envelope.mailFrom || deliveryCandidate.from || ''),
+      to: rcptTo,
+      receivedAtIso: new Date(receivedAt).toISOString(),
+    };
+  }
+
+  public async handleInboundPayload(
+    payloadArg: unknown,
+    handlerArg: TServiceMailInboundHandler,
+  ): Promise<IServiceMailInboundHandleResult> {
+    const message = this.normalizeInboundMessage(payloadArg);
+    const result = await handlerArg(message);
+    return {
+      accepted: result?.accepted !== false,
+      workAppMessageId: result?.workAppMessageId,
+      message: result?.message,
+    };
+  }
+
+  public createInboundHandler(handlerArg: TServiceMailInboundHandler) {
+    return async (payloadArg: unknown) => await this.handleInboundPayload(payloadArg, handlerArg);
   }
 
   public async sendNotification(optionsArg: { toArg: string; subject: string; text: string }) {}
 
   public async sendActionLink(optionsArg: { toArg: string; subject: string; text: string }) {}
+
+  private async readMailEnv(tokenArg?: string): Promise<{
+    from?: string;
+    smtpHost?: string;
+    smtpPort?: string;
+    smtpTlsMode?: string;
+    smtpUsername?: string;
+    smtpPassword?: string;
+  }> {
+    const prefix = tokenArg ? `MAIL_${tokenArg}_` : '';
+    return {
+      from: await this.readMailEnvVar(tokenArg ? `${prefix}FROM` : 'MAIL_FROM'),
+      smtpHost: await this.readMailEnvVar(`${prefix}SMTP_HOST`),
+      smtpPort: await this.readMailEnvVar(`${prefix}SMTP_PORT`),
+      smtpTlsMode: await this.readMailEnvVar(`${prefix}SMTP_TLS_MODE`),
+      smtpUsername: await this.readMailEnvVar(`${prefix}SMTP_USERNAME`),
+      smtpPassword: await this.readMailEnvVar(`${prefix}SMTP_PASSWORD`),
+    };
+  }
+
+  private async readMailEnvVar(envNameArg: string): Promise<string | undefined> {
+    return await this.platformClientRef.getConfiguredEnvVar(envNameArg)
+      || this.getCredentialEnvVarFromBindings(envNameArg);
+  }
+
+  private getCredentialEnvVarFromBindings(envNameArg: string): string | undefined {
+    for (const binding of this.platformClientRef.platformBindings || []) {
+      if (binding.desiredState === 'disabled' || binding.status === 'failed') continue;
+      if (binding.capability !== 'email') continue;
+      for (const credential of binding.credentials || []) {
+        const value = credential.env?.[envNameArg];
+        if (value) return value;
+      }
+    }
+  }
+
+  private hasAnyMailEnvValue(envArg?: {
+    from?: string;
+    smtpHost?: string;
+    smtpPort?: string;
+    smtpTlsMode?: string;
+    smtpUsername?: string;
+    smtpPassword?: string;
+  }): boolean {
+    return Boolean(envArg && Object.values(envArg).some(Boolean));
+  }
+
+  private normalizeTlsMode(valueArg: string): TServiceMailTlsMode {
+    if (valueArg === 'plain' || valueArg === 'starttls' || valueArg === 'implicitTls') return valueArg;
+    throw new Error(`Invalid SMTP_TLS_MODE: ${valueArg}`);
+  }
+
+  private getMailEnvToken(addressArg: string): string {
+    const token = addressArg.trim().toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '').toUpperCase();
+    return /^\d/.test(token) ? `ADDR_${token}` : token;
+  }
+
+  private listToArray(valueArg: string | string[]): string[] {
+    return Array.isArray(valueArg) ? valueArg : [valueArg];
+  }
+
+  private normalizeAttachmentContent(contentArg: string | Uint8Array): string | Buffer {
+    return typeof contentArg === 'string' ? contentArg : Buffer.from(contentArg);
+  }
+
+  private asRecord(valueArg: unknown): Record<string, unknown> {
+    return valueArg && typeof valueArg === 'object' ? valueArg as Record<string, unknown> : {};
+  }
+
+  private normalizeHeaders(headersArg: unknown): Record<string, string | string[]> | undefined {
+    if (!headersArg || typeof headersArg !== 'object') return undefined;
+    const result: Record<string, string | string[]> = {};
+    for (const [key, value] of Object.entries(headersArg as Record<string, unknown>)) {
+      if (Array.isArray(value)) {
+        result[key] = value.map(String);
+      } else if (value !== undefined && value !== null) {
+        result[key] = String(value);
+      }
+    }
+    return result;
+  }
+
+  private extractHeader(rawMessageArg: string, headerNameArg: string): string | undefined {
+    const lowerName = `${headerNameArg.toLowerCase()}:`;
+    for (const line of rawMessageArg.split(/\r?\n/)) {
+      if (!line) return undefined;
+      if (line.toLowerCase().startsWith(lowerName)) {
+        return line.slice(lowerName.length).trim();
+      }
+    }
+  }
 }

package/ts/email/classes.letterconnector.ts

@@ -25,5 +25,6 @@ export class SzLetterConnector {
         'sendLetter'
       );
     const response = await typedRequest.fire(optionsArg);
+    return response.processId;
   }
 }

package/ts/email/classes.pushnotificationconnector.ts

@@ -25,7 +25,7 @@ export class SzPushNotificationConnector {
       );
     const response = await typedRequest.fire(optionsArg);
 
-    if (process.env.SERVEZONE_PLATFORMCLIENT_DEBUG) {
+    if (typeof process !== 'undefined' && process.env?.SERVEZONE_PLATFORMCLIENT_DEBUG) {
       console.log('sendPushNotification response', response);
     }
 

package/ts/index.ts

@@ -1 +1,2 @@
 export * from './classes.platformclient.js';
+export * from './email/classes.emailconnector.js';

package/ts/plugins.ts

@@ -14,6 +14,8 @@ export {
   smartlog,
 }
 
+export const getSmartsmtp = async () => await import('@push.rocks/smartsmtp');
+
 
 // @api.global scope
 import * as typedrequest from '@api.global/typedrequest';