@bernierllc/email-service 4.2.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -16,6 +16,16 @@ import { createRetryState, MemoryRetryStateStorage } from '@bernierllc/retry-sta
16
16
  import { MetricsCollector } from '@bernierllc/retry-metrics';
17
17
  import { EmailServiceError, ProviderError, TemplateError, DeliveryError, DeliveryStatus } from './types.js';
18
18
  export class EmailService {
19
+ db;
20
+ queue;
21
+ templateEngine;
22
+ emailSenders;
23
+ logger;
24
+ config;
25
+ webhookHandlers;
26
+ templateCache;
27
+ retryStorage;
28
+ retryMetrics;
19
29
  constructor(config) {
20
30
  this.config = config;
21
31
  this.db = new DatabaseManager(config.database);
@@ -59,7 +69,7 @@ export class EmailService {
59
69
  catch (error) {
60
70
  const err = error instanceof Error ? error : new Error(String(error));
61
71
  this.logger.error(`Failed to initialize ${providerConfig.type} provider`, err);
62
- throw new ProviderError(`Failed to initialize ${providerConfig.type}`, providerConfig.type, err);
72
+ throw new ProviderError(`Failed to initialize ${providerConfig.type}`, providerConfig.type, { cause: err });
63
73
  }
64
74
  }
65
75
  }
@@ -72,7 +82,7 @@ export class EmailService {
72
82
  catch (error) {
73
83
  const err = error instanceof Error ? error : new Error(String(error));
74
84
  this.logger.error('Failed to initialize email service', err);
75
- throw new EmailServiceError('Initialization failed', 'INIT_ERROR', undefined, err);
85
+ throw new EmailServiceError('Initialization failed', { code: 'INIT_ERROR', cause: err });
76
86
  }
77
87
  }
78
88
  async createTables() {
@@ -237,12 +247,12 @@ export class EmailService {
237
247
  catch (error) {
238
248
  const err = error instanceof Error ? error : new Error(String(error));
239
249
  this.logger.error('Failed to send email', err);
240
- throw new DeliveryError(err.message, request.provider, err);
250
+ throw new DeliveryError(err.message, request.provider, { cause: err });
241
251
  }
242
252
  }
243
253
  async scheduleEmail(request) {
244
254
  if (!this.queue) {
245
- throw new EmailServiceError('Queue not configured for scheduled emails', 'QUEUE_NOT_CONFIGURED');
255
+ throw new EmailServiceError('Queue not configured for scheduled emails', { code: 'QUEUE_NOT_CONFIGURED' });
246
256
  }
247
257
  const delay = request.scheduledAt.getTime() - Date.now();
248
258
  const priority = request.priority === 'high' ? JobPriority.HIGH :
@@ -315,7 +325,7 @@ export class EmailService {
315
325
  catch (error) {
316
326
  const err = error instanceof Error ? error : new Error(String(error));
317
327
  this.logger.error('Failed to create template', err);
318
- throw new TemplateError(err.message, err);
328
+ throw new TemplateError(err.message, { cause: err });
319
329
  }
320
330
  }
321
331
  async getTemplate(id) {
@@ -582,7 +592,7 @@ export class EmailService {
582
592
  async sendMagicLink(config) {
583
593
  try {
584
594
  if (!this.config.magicLink?.secret) {
585
- throw new EmailServiceError('Magic link configuration is missing. Please provide magicLink.secret in EmailServiceConfig', 'MAGIC_LINK_NOT_CONFIGURED');
595
+ throw new EmailServiceError('Magic link configuration is missing. Please provide magicLink.secret in EmailServiceConfig', { code: 'MAGIC_LINK_NOT_CONFIGURED' });
586
596
  }
587
597
  // Generate secure token
588
598
  const expirationMinutes = config.expirationMinutes || this.config.magicLink.expirationMinutes || 60;
@@ -0,0 +1,52 @@
1
+ import type { EmailProvider } from './types.js';
2
+ /**
3
+ * Typed error code union for email-service errors.
4
+ */
5
+ export type EmailServiceErrorCode = 'EMAIL_SERVICE_ERROR' | 'PROVIDER_ERROR' | 'TEMPLATE_ERROR' | 'DELIVERY_ERROR' | 'INIT_ERROR' | 'QUEUE_NOT_CONFIGURED' | 'MAGIC_LINK_NOT_CONFIGURED' | string;
6
+ /**
7
+ * Options bag accepted by all email-service error classes.
8
+ *
9
+ * - `cause`: chained underlying error (ES2022 Error.cause).
10
+ * - `code`: a typed error code from {@link EmailServiceErrorCode}.
11
+ * - `context`: arbitrary structured context — provider/templateId/etc.
12
+ */
13
+ export interface EmailServiceErrorOptions {
14
+ cause?: Error;
15
+ code?: EmailServiceErrorCode;
16
+ context?: Record<string, unknown>;
17
+ }
18
+ /**
19
+ * Base error class for email-service.
20
+ *
21
+ * Uses native ES2022 `Error.cause` for error chaining — read the underlying
22
+ * error via `error.cause`. Subclass-specific fields (e.g. `provider`) live on
23
+ * `error.context` since 5.0.0 — read via `error.context?.provider`.
24
+ */
25
+ export declare class EmailServiceError extends Error {
26
+ readonly code: EmailServiceErrorCode;
27
+ readonly context?: Record<string, unknown>;
28
+ constructor(message: string, options?: EmailServiceErrorOptions);
29
+ }
30
+ /**
31
+ * Provider-specific error.
32
+ *
33
+ * Convenience constructor accepts `provider`; stored on `context.provider`.
34
+ */
35
+ export declare class ProviderError extends EmailServiceError {
36
+ constructor(message: string, provider: EmailProvider, options?: Omit<EmailServiceErrorOptions, 'code'>);
37
+ }
38
+ /**
39
+ * Template-related error.
40
+ */
41
+ export declare class TemplateError extends EmailServiceError {
42
+ constructor(message: string, options?: Omit<EmailServiceErrorOptions, 'code'>);
43
+ }
44
+ /**
45
+ * Delivery-related error.
46
+ *
47
+ * Convenience constructor accepts an optional `provider`; stored on
48
+ * `context.provider` when present.
49
+ */
50
+ export declare class DeliveryError extends EmailServiceError {
51
+ constructor(message: string, provider?: EmailProvider, options?: Omit<EmailServiceErrorOptions, 'code'>);
52
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,72 @@
1
+ /*
2
+ Copyright (c) 2025 Bernier LLC
3
+
4
+ This file is licensed to the client under a limited-use license.
5
+ The client may use and modify this code *only within the scope of the project it was delivered for*.
6
+ Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
+ */
8
+ /**
9
+ * Base error class for email-service.
10
+ *
11
+ * Uses native ES2022 `Error.cause` for error chaining — read the underlying
12
+ * error via `error.cause`. Subclass-specific fields (e.g. `provider`) live on
13
+ * `error.context` since 5.0.0 — read via `error.context?.provider`.
14
+ */
15
+ export class EmailServiceError extends Error {
16
+ code;
17
+ context;
18
+ constructor(message, options) {
19
+ super(message, options?.cause ? { cause: options.cause } : undefined);
20
+ this.name = 'EmailServiceError';
21
+ this.code = options?.code ?? 'EMAIL_SERVICE_ERROR';
22
+ if (options?.context !== undefined) {
23
+ this.context = options.context;
24
+ }
25
+ Error.captureStackTrace?.(this, this.constructor);
26
+ }
27
+ }
28
+ /**
29
+ * Provider-specific error.
30
+ *
31
+ * Convenience constructor accepts `provider`; stored on `context.provider`.
32
+ */
33
+ export class ProviderError extends EmailServiceError {
34
+ constructor(message, provider, options) {
35
+ super(message, {
36
+ ...options,
37
+ code: 'PROVIDER_ERROR',
38
+ context: { ...(options?.context ?? {}), provider },
39
+ });
40
+ this.name = 'ProviderError';
41
+ }
42
+ }
43
+ /**
44
+ * Template-related error.
45
+ */
46
+ export class TemplateError extends EmailServiceError {
47
+ constructor(message, options) {
48
+ super(message, {
49
+ ...options,
50
+ code: 'TEMPLATE_ERROR',
51
+ });
52
+ this.name = 'TemplateError';
53
+ }
54
+ }
55
+ /**
56
+ * Delivery-related error.
57
+ *
58
+ * Convenience constructor accepts an optional `provider`; stored on
59
+ * `context.provider` when present.
60
+ */
61
+ export class DeliveryError extends EmailServiceError {
62
+ constructor(message, provider, options) {
63
+ super(message, {
64
+ ...options,
65
+ code: 'DELIVERY_ERROR',
66
+ context: provider !== undefined
67
+ ? { ...(options?.context ?? {}), provider }
68
+ : options?.context,
69
+ });
70
+ this.name = 'DeliveryError';
71
+ }
72
+ }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,5 @@
1
1
  export { EmailService } from './email-service.js';
2
2
  export type { EmailProvider, ProviderConfig, SMTPConfig, RateLimitConfig, EmailServiceConfig, EmailAddress, EmailAttachment, EmailRequest, EmailResult, SendEmailResult, EmailTemplate, TemplateCreateRequest, TemplateUpdateRequest, DeliveryRecord, DeliveryEvent, DeliveryStats, Subscriber, SubscriberCreateRequest, SubscriberUpdateRequest, SubscriberList, WebhookEvent, WebhookHandler, MagicLinkEmail, MagicLinkResult } from './types.js';
3
- export { DeliveryStatus, SubscriberStatus, EmailServiceError, ProviderError, TemplateError, DeliveryError } from './types.js';
3
+ export { DeliveryStatus, SubscriberStatus, } from './types.js';
4
+ export { EmailServiceError, ProviderError, TemplateError, DeliveryError, } from './errors.js';
5
+ export type { EmailServiceErrorCode, EmailServiceErrorOptions, } from './errors.js';
package/dist/index.js CHANGED
@@ -6,4 +6,5 @@ The client may use and modify this code *only within the scope of the project it
6
6
  Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
7
7
  */
8
8
  export { EmailService } from './email-service.js';
9
- export { DeliveryStatus, SubscriberStatus, EmailServiceError, ProviderError, TemplateError, DeliveryError } from './types.js';
9
+ export { DeliveryStatus, SubscriberStatus, } from './types.js';
10
+ export { EmailServiceError, ProviderError, TemplateError, DeliveryError, } from './errors.js';
package/dist/types.d.ts CHANGED
@@ -218,21 +218,8 @@ export interface WebhookEvent {
218
218
  export interface WebhookHandler {
219
219
  (event: WebhookEvent): Promise<void>;
220
220
  }
221
- export declare class EmailServiceError extends Error {
222
- readonly code?: string | undefined;
223
- readonly provider?: EmailProvider | undefined;
224
- readonly cause?: Error | undefined;
225
- constructor(message: string, code?: string | undefined, provider?: EmailProvider | undefined, cause?: Error | undefined);
226
- }
227
- export declare class ProviderError extends EmailServiceError {
228
- constructor(message: string, provider: EmailProvider, cause?: Error);
229
- }
230
- export declare class TemplateError extends EmailServiceError {
231
- constructor(message: string, cause?: Error);
232
- }
233
- export declare class DeliveryError extends EmailServiceError {
234
- constructor(message: string, provider?: EmailProvider, cause?: Error);
235
- }
221
+ export { EmailServiceError, ProviderError, TemplateError, DeliveryError, } from './errors.js';
222
+ export type { EmailServiceErrorCode, EmailServiceErrorOptions, } from './errors.js';
236
223
  export interface MagicLinkEmail {
237
224
  recipient: string;
238
225
  purpose: string;
package/dist/types.js CHANGED
@@ -26,30 +26,5 @@ export var SubscriberStatus;
26
26
  SubscriberStatus["COMPLAINED"] = "complained";
27
27
  })(SubscriberStatus || (SubscriberStatus = {}));
28
28
  // ===== Errors =====
29
- export class EmailServiceError extends Error {
30
- constructor(message, code, provider, cause) {
31
- super(message);
32
- this.code = code;
33
- this.provider = provider;
34
- this.cause = cause;
35
- this.name = 'EmailServiceError';
36
- }
37
- }
38
- export class ProviderError extends EmailServiceError {
39
- constructor(message, provider, cause) {
40
- super(message, 'PROVIDER_ERROR', provider, cause);
41
- this.name = 'ProviderError';
42
- }
43
- }
44
- export class TemplateError extends EmailServiceError {
45
- constructor(message, cause) {
46
- super(message, 'TEMPLATE_ERROR', undefined, cause);
47
- this.name = 'TemplateError';
48
- }
49
- }
50
- export class DeliveryError extends EmailServiceError {
51
- constructor(message, provider, cause) {
52
- super(message, 'DELIVERY_ERROR', provider, cause);
53
- this.name = 'DeliveryError';
54
- }
55
- }
29
+ // Re-exported from ./errors for backward-compat import paths.
30
+ export { EmailServiceError, ProviderError, TemplateError, DeliveryError, } from './errors.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bernierllc/email-service",
3
- "version": "4.2.0",
3
+ "version": "6.0.0",
4
4
  "description": "Comprehensive email service orchestrating template management, multi-provider delivery, tracking, and subscriber management",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -27,14 +27,14 @@
27
27
  "license": "PROPRIETARY",
28
28
  "dependencies": {
29
29
  "@bernierllc/config-manager": "1.4.0",
30
- "@bernierllc/database-adapter": "1.5.0",
31
- "@bernierllc/email-parser": "0.7.0",
32
30
  "@bernierllc/crypto-utils": "1.4.0",
33
- "@bernierllc/email-sender": "5.5.0",
31
+ "@bernierllc/email-parser": "0.7.0",
32
+ "@bernierllc/email-sender": "5.7.0",
34
33
  "@bernierllc/email-validator": "3.4.0",
34
+ "@bernierllc/database-adapter": "1.5.0",
35
35
  "@bernierllc/logger": "1.7.0",
36
- "@bernierllc/queue-manager": "1.5.0",
37
36
  "@bernierllc/retry-metrics": "0.5.0",
37
+ "@bernierllc/queue-manager": "1.5.0",
38
38
  "@bernierllc/retry-policy": "0.7.0",
39
39
  "@bernierllc/retry-state": "0.5.0",
40
40
  "@bernierllc/template-engine": "0.7.0",