@erxes/api-shared 0.0.0-stage → 3.2.19-1

package/src/utils/email/resolveProvider.ts

@@ -0,0 +1,75 @@
+import { getEmailProviderConfigFingerprint } from './config';
+import { DEFAULT_EMAIL_PROVIDER } from './constants';
+import { SendgridEmailProvider } from './providers/sendgrid';
+import { SesEmailProvider } from './providers/ses';
+import { SmtpEmailProvider } from './providers/smtp';
+import {
+  IEmailProvider,
+  IEmailProviderConfig,
+  TEmailProviderName,
+} from './types';
+
+export const resolveEmailProviderName = (
+  config: IEmailProviderConfig,
+): TEmailProviderName => {
+  const value = (config.DEFAULT_EMAIL_SERVICE || '').trim();
+
+  if (value.toLowerCase() === 'sendgrid') {
+    return 'sendgrid';
+  }
+
+  if (value.toLowerCase() === 'custom') {
+    return 'custom';
+  }
+
+  if (value.toUpperCase() === 'SES') {
+    return 'SES';
+  }
+
+  return DEFAULT_EMAIL_PROVIDER;
+};
+
+export const createEmailProvider = (
+  config: IEmailProviderConfig,
+): IEmailProvider => {
+  switch (resolveEmailProviderName(config)) {
+    case 'sendgrid':
+      return new SendgridEmailProvider(config);
+    case 'custom':
+      return new SmtpEmailProvider(config);
+    default:
+      return new SesEmailProvider(config);
+  }
+};
+
+const providerCache = new Map<
+  string,
+  { fingerprint: string; provider: IEmailProvider }
+>();
+
+export const getEmailProvider = (
+  cacheKey: string,
+  config: IEmailProviderConfig,
+): IEmailProvider => {
+  const fingerprint = getEmailProviderConfigFingerprint(config);
+  const cached = providerCache.get(cacheKey);
+
+  if (cached && cached.fingerprint === fingerprint) {
+    return cached.provider;
+  }
+
+  const provider = createEmailProvider(config);
+
+  providerCache.set(cacheKey, { fingerprint, provider });
+
+  return provider;
+};
+
+export const clearEmailProviderCache = (cacheKey?: string) => {
+  if (cacheKey) {
+    providerCache.delete(cacheKey);
+    return;
+  }
+
+  providerCache.clear();
+};

package/src/utils/email/service.ts

@@ -0,0 +1,192 @@
+import { getEmailProvider } from './resolveProvider';
+import {
+  IEmailProviderConfig,
+  IOutboundEmail,
+  ISentEmail,
+  TEmailProviderName,
+} from './types';
+
+export const EMAIL_DELIVERY_ID_KEY = 'EmailDeliveryId';
+
+export const EMAIL_SUBDOMAIN_KEY = 'Subdomain';
+
+export interface IDeliveryLogInput {
+  toEmails: string[];
+  ccEmails?: string[];
+  from: string;
+  subject: string;
+  provider: TEmailProviderName;
+  source?: string;
+  sourceId?: string;
+  userId?: string;
+  notificationId?: string;
+}
+
+export interface IDeliveryLogPatch {
+  status: 'sent' | 'failed';
+  sentAt: Date;
+  messageId?: string;
+  providerResponse?: string;
+  rejected?: string[];
+  error?: string;
+}
+
+export interface IDeliveryLogPort {
+  create(input: IDeliveryLogInput): Promise<string | undefined>;
+  update(id: string, patch: IDeliveryLogPatch): Promise<void>;
+}
+
+export interface ISuppressionPort {
+  blocked(emails: string[], source?: string): Promise<string[]>;
+}
+
+export interface ISendOutcome extends ISentEmail {
+  deliveryId?: string;
+  skipped?: boolean;
+  suppressed?: string[];
+}
+
+export const toDeliveryLogProvider = (
+  name: TEmailProviderName,
+): 'sendgrid' | 'smtp' | 'ses' => {
+  if (name === 'sendgrid') {
+    return 'sendgrid';
+  }
+
+  if (name === 'SES') {
+    return 'ses';
+  }
+
+  return 'smtp';
+};
+
+const toErrorMessage = (error: unknown) =>
+  error instanceof Error ? error.message : String(error);
+
+export const deliverEmail = async ({
+  cacheKey,
+  config,
+  message,
+  log,
+  suppression,
+  meta,
+}: {
+  cacheKey: string;
+  config: IEmailProviderConfig;
+  message: IOutboundEmail;
+  log?: IDeliveryLogPort;
+  suppression?: ISuppressionPort;
+  meta?: {
+    source?: string;
+    sourceId?: string;
+    userId?: string;
+    notificationId?: string;
+    subdomain?: string;
+  };
+}): Promise<ISendOutcome> => {
+  const provider = getEmailProvider(cacheKey, config);
+
+  let recipients = message;
+  let suppressed: string[] = [];
+
+  if (suppression) {
+    suppressed = await suppression.blocked(
+      [...message.to, ...(message.cc || []), ...(message.bcc || [])],
+      meta?.source,
+    );
+
+    if (suppressed.length) {
+      const closed = new Set(suppressed);
+      const to = message.to.filter((email) => !closed.has(email));
+
+      if (!to.length) {
+        return {
+          messageId: '',
+          provider: provider.name,
+          accepted: [],
+          rejected: [],
+          skipped: true,
+          suppressed,
+        };
+      }
+
+      recipients = {
+        ...message,
+        to,
+        cc: (message.cc || []).filter((email) => !closed.has(email)),
+        bcc: (message.bcc || []).filter((email) => !closed.has(email)),
+      };
+    }
+  }
+
+  let deliveryId: string | undefined;
+
+  if (log) {
+    try {
+      deliveryId = await log.create({
+        toEmails: recipients.to,
+        ccEmails: recipients.cc,
+        from: recipients.from,
+        subject: recipients.subject,
+        provider: provider.name,
+        source: meta?.source,
+        sourceId: meta?.sourceId,
+        userId: meta?.userId,
+        notificationId: meta?.notificationId,
+      });
+    } catch (error) {
+      console.error(
+        `Failed to record email delivery: ${toErrorMessage(error)}`,
+      );
+    }
+  }
+
+  const tracking = {
+    ...(deliveryId ? { [EMAIL_DELIVERY_ID_KEY]: deliveryId } : {}),
+    ...(meta?.subdomain ? { [EMAIL_SUBDOMAIN_KEY]: meta.subdomain } : {}),
+  };
+
+  const outbound: IOutboundEmail = Object.keys(tracking).length
+    ? {
+        ...recipients,
+        customArgs: { ...(recipients.customArgs || {}), ...tracking },
+      }
+    : recipients;
+
+  try {
+    const result = await provider.send(outbound);
+
+    if (log && deliveryId) {
+      await log
+        .update(deliveryId, {
+          status: 'sent',
+          sentAt: new Date(),
+          messageId: result.messageId,
+          rejected: result.rejected,
+        })
+        .catch((error) => {
+          console.error(
+            `Failed to update email delivery: ${toErrorMessage(error)}`,
+          );
+        });
+    }
+
+    return {
+      ...result,
+      deliveryId,
+      suppressed: suppressed.length ? suppressed : undefined,
+    };
+  } catch (error) {
+    if (log && deliveryId) {
+      await log
+        .update(deliveryId, {
+          status: 'failed',
+          sentAt: new Date(),
+          error: toErrorMessage(error),
+        })
+        .catch(() => undefined);
+    }
+
+    throw error;
+  }
+};

package/src/utils/email/types.ts

@@ -0,0 +1,127 @@
+export type TEmailProviderName = 'SES' | 'sendgrid' | 'custom';
+
+export interface IEmailAttachment {
+  filename: string;
+  path?: string;
+  content?: string;
+  contentType?: string;
+}
+
+export interface IOutboundEmail {
+  from: string;
+  to: string[];
+  cc?: string[];
+  bcc?: string[];
+  replyTo?: string;
+  subject: string;
+  html: string;
+  text?: string;
+  attachments?: IEmailAttachment[];
+  headers?: Record<string, string>;
+  customArgs?: Record<string, string>;
+}
+
+export interface ISentEmail {
+  messageId: string;
+  provider: TEmailProviderName;
+  accepted: string[];
+  rejected: string[];
+}
+
+export type TDnsRecordType = 'CNAME' | 'TXT' | 'MX';
+
+export interface IDnsRecord {
+  type: TDnsRecordType;
+  host: string;
+  data: string;
+  valid: boolean;
+}
+
+export type TSenderStatus = 'pending' | 'verified' | 'failed';
+
+export type TSenderType = 'single' | 'domain';
+
+export interface ISender {
+  id: string;
+  type: TSenderType;
+  value: string;
+  name?: string;
+  status: TSenderStatus;
+  dnsRecords?: IDnsRecord[];
+}
+
+export interface ISingleSenderInput {
+  email: string;
+  name?: string;
+  replyTo?: string;
+  address?: string;
+  city?: string;
+  country?: string;
+}
+
+export interface IEmailProviderConfig {
+  DEFAULT_EMAIL_SERVICE?: string;
+
+  AWS_SES_ACCESS_KEY_ID?: string;
+  AWS_SES_SECRET_ACCESS_KEY?: string;
+  AWS_REGION?: string;
+  AWS_SES_CONFIG_SET?: string;
+
+  SENDGRID_API_KEY?: string;
+  SENDGRID_SUBUSER?: string;
+
+  MAIL_SERVICE?: string;
+  MAIL_HOST?: string;
+  MAIL_PORT?: string;
+  MAIL_USER?: string;
+  MAIL_PASS?: string;
+}
+
+export interface IEmailProvider {
+  readonly name: TEmailProviderName;
+
+  send(message: IOutboundEmail): Promise<ISentEmail>;
+
+  listSingleSenders(ids?: string[]): Promise<ISender[]>;
+  listAuthenticatedDomains(domains?: string[]): Promise<ISender[]>;
+
+  verifySingleSender(input: ISingleSenderInput): Promise<ISender>;
+
+  removeSender(id: string): Promise<void>;
+
+  authenticateDomain(domain: string): Promise<ISender>;
+
+  validateDomain(id: string): Promise<ISender>;
+}
+
+export class EmailProviderNotSupportedError extends Error {
+  constructor(provider: string, operation: string) {
+    super(
+      `"${operation}" is not supported by the "${provider}" email provider`,
+    );
+    this.name = 'EmailProviderNotSupportedError';
+  }
+}
+
+export class EmailProviderConfigError extends Error {
+  constructor(provider: string, missing: string[]) {
+    super(
+      `"${provider}" email provider is missing configuration: ${missing.join(
+        ', ',
+      )}`,
+    );
+    this.name = 'EmailProviderConfigError';
+  }
+}
+
+export class EmailProviderRequestError extends Error {
+  public status: number;
+  public body: string;
+
+  constructor(provider: string, status: number, body: string) {
+    super(`"${provider}" API request failed with status ${status}: ${body}`);
+    this.name = 'EmailProviderRequestError';
+    this.status = status;
+    this.body = body;
+  }
+}

package/src/utils/errorClassifier.test.ts

@@ -0,0 +1,231 @@
+import {
+  classifyError,
+  isExpectedError,
+  extractMessage,
+  sentryExpectedErrorFilter,
+  ExpectedError,
+  createExpectedError,
+  EXPECTED_ERROR_NAME,
+} from './errorClassifier';
+
+describe('errorClassifier', () => {
+  describe('classifyError', () => {
+    test.each([
+      ['User not found', 'EXPECTED', true, 200],
+      ['Email already exists', 'EXPECTED', true, 200],
+      ['Name is required', 'EXPECTED', true, 200],
+      ['Invalid email format', 'EXPECTED', true, 200],
+      ['Wrong password', 'EXPECTED', true, 200],
+      ['Permission denied', 'EXPECTED', true, 200],
+      ['Not authenticated', 'EXPECTED', true, 200],
+    ])('should classify "%s" as EXPECTED', (msg, category, isExpected, statusCode) => {
+      const result = classifyError(new Error(msg));
+      expect(result.category).toBe(category);
+      expect(result.isExpected).toBe(isExpected);
+      expect(result.statusCode).toBe(statusCode);
+    });
+
+    // Regression: real prod Sentry noise that previously leaked through because
+    // the messages don't contain "is required"/"are required"/etc.
+    test.each([
+      ['Login required'],
+      ['Permission required'],
+      ['OAuth scope required'],
+      ['Client portal required'],
+      ['Client portal user required'],
+      ['You do not have permission to manage this identifier'],
+      ['Access denied: You do not have access to this private pipeline'],
+      ['This operation is only allowed in saas version.'],
+      ['Start date must be before end date'],
+    ])('should classify auth/business noise "%s" as EXPECTED', (msg) => {
+      const result = classifyError(new Error(msg));
+      expect(result.category).toBe('EXPECTED');
+      expect(result.isExpected).toBe(true);
+      expect(result.statusCode).toBe(200);
+    });
+
+    it('should classify "MongoNetworkError" as SYSTEM', () => {
+      const error = new Error('MongoNetworkError: connection failed');
+      const result = classifyError(error);
+      expect(result.category).toBe('SYSTEM');
+      expect(result.isExpected).toBe(false);
+      expect(result.statusCode).toBe(500);
+    });
+
+    test.each([
+      ['Request timeout', 'PROVIDER', false, 502],
+      ['connect ECONNREFUSED 127.0.0.1:27017', 'PROVIDER', false, 502],
+    ])('should classify "%s" as PROVIDER', (msg, category, isExpected, statusCode) => {
+      const result = classifyError(new Error(msg));
+      expect(result.category).toBe(category);
+      expect(result.isExpected).toBe(isExpected);
+      expect(result.statusCode).toBe(statusCode);
+    });
+
+    it('should classify unknown errors as UNKNOWN', () => {
+      const result = classifyError(new Error('Something weird happened'));
+      expect(result.category).toBe('UNKNOWN');
+      expect(result.isExpected).toBe(false);
+      expect(result.statusCode).toBe(500);
+    });
+
+    it('should classify string errors', () => {
+      const result = classifyError('Not found');
+      expect(result.category).toBe('EXPECTED');
+    });
+
+    it('should classify by error code', () => {
+      const error = new Error('Validation failed') as any;
+      error.code = 'VALIDATION_ERROR';
+      const result = classifyError(error);
+      expect(result.category).toBe('EXPECTED');
+    });
+  });
+
+  describe('ExpectedError (explicit marker)', () => {
+    it('is always EXPECTED regardless of message wording', () => {
+      // A message that matches NONE of the regex patterns must still be expected.
+      const result = classifyError(new ExpectedError('totally novel wording xyz'));
+      expect(result.category).toBe('EXPECTED');
+      expect(result.isExpected).toBe(true);
+      expect(result.statusCode).toBe(200);
+    });
+
+    it('beats SYSTEM patterns when explicitly marked', () => {
+      // Even a message containing a SYSTEM keyword stays EXPECTED when the
+      // thrower has declared intent via ExpectedError.
+      const result = classifyError(new ExpectedError('TypeError-looking message'));
+      expect(result.category).toBe('EXPECTED');
+    });
+
+    it('createExpectedError produces an ExpectedError', () => {
+      const err = createExpectedError('Login required', 'UNAUTHORIZED');
+      expect(err).toBeInstanceOf(ExpectedError);
+      expect(err.name).toBe(EXPECTED_ERROR_NAME);
+      expect(err.code).toBe('UNAUTHORIZED');
+      expect(err.isExpected).toBe(true);
+      expect(classifyError(err).category).toBe('EXPECTED');
+    });
+
+    it('honours a plain object with isExpected === true', () => {
+      const result = classifyError({ message: 'whatever', isExpected: true });
+      expect(result.category).toBe('EXPECTED');
+    });
+  });
+
+  describe('isExpectedError', () => {
+    it('should return true for expected errors', () => {
+      expect(isExpectedError(new Error('Not found'))).toBe(true);
+      expect(isExpectedError(new Error('Already exists'))).toBe(true);
+    });
+
+    it('should return false for system errors', () => {
+      expect(isExpectedError(new Error('MongoNetworkError'))).toBe(false);
+    });
+  });
+
+  describe('extractMessage', () => {
+    it('should extract message from Error', () => {
+      expect(extractMessage(new Error('test'))).toBe('test');
+    });
+
+    it('should return string as-is', () => {
+      expect(extractMessage('test')).toBe('test');
+    });
+
+    it('should handle objects with message property', () => {
+      expect(extractMessage({ message: 'test' })).toBe('test');
+    });
+
+    it('should handle unknown types', () => {
+      expect(extractMessage(123)).toBe('123');
+    });
+  });
+
+  describe('SYSTEM vs EXPECTED ordering', () => {
+    it('should classify "Cannot find module" as SYSTEM, not EXPECTED', () => {
+      const result = classifyError(new Error("Cannot find module 'lodash'"));
+      expect(result.category).toBe('SYSTEM');
+      expect(result.isExpected).toBe(false);
+      expect(result.statusCode).toBe(500);
+    });
+
+    it('should classify "Missing environment variable" as SYSTEM, not EXPECTED', () => {
+      const result = classifyError(new Error('Missing environment variable: API_KEY'));
+      expect(result.category).toBe('SYSTEM');
+      expect(result.isExpected).toBe(false);
+      expect(result.statusCode).toBe(500);
+    });
+
+    it('should classify Mongoose BSON errors as SYSTEM', () => {
+      const error = new Error('BSONTypeError: Cast to ObjectId failed for value "abc" at path "_id"');
+      const result = classifyError(error);
+      expect(result.category).toBe('SYSTEM');
+      expect(result.isExpected).toBe(false);
+      expect(result.statusCode).toBe(500);
+    });
+
+    it('should classify Cast to ObjectId as SYSTEM', () => {
+      const error = new Error('Cast to ObjectId failed for value "invalid"');
+      const result = classifyError(error);
+      expect(result.category).toBe('SYSTEM');
+      expect(result.isExpected).toBe(false);
+      expect(result.statusCode).toBe(500);
+    });
+  });
+
+  describe('sentryExpectedErrorFilter', () => {
+    it('should return null for EXPECTED errors', () => {
+      const event = {
+        exception: {
+          values: [{ value: 'User not found' }]
+        }
+      };
+      expect(sentryExpectedErrorFilter(event as any)).toBeNull();
+    });
+
+    it('should return event for SYSTEM errors', () => {
+      const event = {
+        exception: {
+          values: [{ value: 'MongoNetworkError: connection failed' }]
+        }
+      };
+      expect(sentryExpectedErrorFilter(event as any)).toBe(event as any);
+    });
+
+    it('should return event for PROVIDER errors', () => {
+      const event = {
+        exception: {
+          values: [{ value: 'Request timeout' }]
+        }
+      };
+      expect(sentryExpectedErrorFilter(event as any)).toBe(event as any);
+    });
+
+    it('should return event when no exception value', () => {
+      const event = { exception: { values: [{}] } };
+      expect(sentryExpectedErrorFilter(event as any)).toBe(event as any);
+    });
+
+    it('should return event when no exception', () => {
+      const event = {};
+      expect(sentryExpectedErrorFilter(event as any)).toBe(event as any);
+    });
+
+    it('should drop events by ExpectedError type even if message is unmatched', () => {
+      const event = {
+        exception: {
+          values: [{ type: EXPECTED_ERROR_NAME, value: 'novel wording xyz' }],
+        },
+      };
+      expect(sentryExpectedErrorFilter(event as any)).toBeNull();
+    });
+
+    it('should drop "Login required" (regression)', () => {
+      const event = {
+        exception: { values: [{ type: 'Error', value: 'Login required' }] },
+      };
+      expect(sentryExpectedErrorFilter(event as any)).toBeNull();
+    });
+  });
+});