@bernierllc/email-webhook-events 1.4.1 → 1.6.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.
- package/dist/EmailWebhookEventsService.js +4 -0
- package/dist/EmailWebhookEventsService.js.map +1 -1
- package/dist/analytics/AnalyticsEngine.js +2 -1
- package/dist/analytics/AnalyticsEngine.js.map +1 -1
- package/dist/errors.d.ts +12 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +25 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/persistence/InMemoryPersistenceAdapter.js +2 -4
- package/dist/persistence/InMemoryPersistenceAdapter.js.map +1 -1
- package/package.json +6 -2
- package/.eslintrc.cjs +0 -30
- package/CHANGELOG.md +0 -139
- package/__tests__/EmailWebhookEventsService.test.ts +0 -251
- package/__tests__/WebhookEventCallbacks.test.ts +0 -343
- package/__tests__/analytics/AnalyticsEngine.test.ts +0 -250
- package/__tests__/fixtures/sendgrid-webhooks/.gitkeep +0 -0
- package/__tests__/fixtures/sendgrid-webhooks/README.md +0 -63
- package/__tests__/fixtures/sendgrid-webhooks/deferred.json +0 -31
- package/__tests__/fixtures/sendgrid-webhooks/delivered.json +0 -83
- package/__tests__/fixtures/sendgrid-webhooks/open.json +0 -83
- package/__tests__/integration/ngrok-tunnel-manager.ts +0 -88
- package/__tests__/integration/sendgrid-webhook-integration.test.ts +0 -272
- package/__tests__/integration/webhook-server.ts +0 -188
- package/__tests__/mocks/README.md +0 -172
- package/__tests__/mocks/index.ts +0 -94
- package/__tests__/mocks/sendgrid-api-responses.ts +0 -391
- package/__tests__/mocks/sendgrid-webhook-payloads.ts +0 -463
- package/__tests__/normalizers/MailgunNormalizer.test.ts +0 -149
- package/__tests__/normalizers/PostmarkNormalizer.test.ts +0 -112
- package/__tests__/normalizers/SESNormalizer.test.ts +0 -168
- package/__tests__/normalizers/SMTP2GONormalizer.test.ts +0 -83
- package/__tests__/normalizers/SendGridNormalizer.test.ts +0 -181
- package/__tests__/persistence/PersistenceAdapter.test.ts +0 -103
- package/jest.config.cjs +0 -38
- package/src/EmailWebhookEventsService.ts +0 -290
- package/src/analytics/AnalyticsEngine.ts +0 -230
- package/src/index.ts +0 -40
- package/src/normalizers/EventNormalizer.ts +0 -13
- package/src/normalizers/MailgunNormalizer.ts +0 -72
- package/src/normalizers/PostmarkNormalizer.ts +0 -72
- package/src/normalizers/SESNormalizer.ts +0 -117
- package/src/normalizers/SMTP2GONormalizer.ts +0 -54
- package/src/normalizers/SendGridNormalizer.ts +0 -63
- package/src/persistence/InMemoryPersistenceAdapter.ts +0 -68
- package/src/persistence/PersistenceAdapter.ts +0 -15
- package/src/types.ts +0 -261
- package/tsconfig.json +0 -31
|
@@ -1,72 +0,0 @@
|
|
|
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
|
-
import { EventNormalizer } from './EventNormalizer';
|
|
10
|
-
import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
|
|
11
|
-
|
|
12
|
-
export class PostmarkNormalizer implements EventNormalizer {
|
|
13
|
-
normalize(webhook: WebhookPayload): EmailEvent {
|
|
14
|
-
const event = webhook.payload as Record<string, unknown>;
|
|
15
|
-
|
|
16
|
-
return {
|
|
17
|
-
id: this.generateEventId(event),
|
|
18
|
-
emailId: (event.MessageID as string) || '',
|
|
19
|
-
messageId: (event.MessageID as string) || '',
|
|
20
|
-
type: this.mapEventType(event.RecordType as string),
|
|
21
|
-
recipient: (event.Recipient as string) || '',
|
|
22
|
-
timestamp: new Date(event.ReceivedAt as string),
|
|
23
|
-
provider: EmailProvider.POSTMARK,
|
|
24
|
-
metadata: {
|
|
25
|
-
url: event.OriginalLink as string | undefined,
|
|
26
|
-
bounceType: this.mapBounceType(event.Type as string | undefined),
|
|
27
|
-
bounceReason: event.Description as string | undefined,
|
|
28
|
-
bounceCode: event.TypeCode?.toString(),
|
|
29
|
-
complaintFeedbackType: event.Type as string | undefined,
|
|
30
|
-
userAgent: event.UserAgent as string | undefined,
|
|
31
|
-
deviceType: this.detectDeviceType(event.UserAgent as string | undefined),
|
|
32
|
-
location: {
|
|
33
|
-
country: (event.Geo as Record<string, string> | undefined)?.Country,
|
|
34
|
-
region: (event.Geo as Record<string, string> | undefined)?.Region,
|
|
35
|
-
city: (event.Geo as Record<string, string> | undefined)?.City
|
|
36
|
-
}
|
|
37
|
-
},
|
|
38
|
-
rawEvent: event
|
|
39
|
-
};
|
|
40
|
-
}
|
|
41
|
-
|
|
42
|
-
private mapEventType(postmarkEvent: string): EmailEventType {
|
|
43
|
-
const mapping: Record<string, EmailEventType> = {
|
|
44
|
-
'Delivery': EmailEventType.DELIVERED,
|
|
45
|
-
'Open': EmailEventType.OPENED,
|
|
46
|
-
'Click': EmailEventType.CLICKED,
|
|
47
|
-
'Bounce': EmailEventType.BOUNCED,
|
|
48
|
-
'SpamComplaint': EmailEventType.COMPLAINED,
|
|
49
|
-
'SubscriptionChange': EmailEventType.UNSUBSCRIBED
|
|
50
|
-
};
|
|
51
|
-
return mapping[postmarkEvent] || EmailEventType.FAILED;
|
|
52
|
-
}
|
|
53
|
-
|
|
54
|
-
private mapBounceType(bounceType?: string): 'hard' | 'soft' | undefined {
|
|
55
|
-
if (!bounceType) return undefined;
|
|
56
|
-
if (bounceType.includes('Hard')) return 'hard';
|
|
57
|
-
if (bounceType.includes('Soft')) return 'soft';
|
|
58
|
-
return undefined;
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
private generateEventId(event: Record<string, unknown>): string {
|
|
62
|
-
return `postmark-${(event.MessageID as string) || ''}-${Date.now()}`;
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
private detectDeviceType(userAgent?: string): 'desktop' | 'mobile' | 'tablet' | 'unknown' {
|
|
66
|
-
if (!userAgent) return 'unknown';
|
|
67
|
-
const ua = userAgent.toLowerCase();
|
|
68
|
-
if (ua.includes('mobile')) return 'mobile';
|
|
69
|
-
if (ua.includes('tablet') || ua.includes('ipad')) return 'tablet';
|
|
70
|
-
return 'desktop';
|
|
71
|
-
}
|
|
72
|
-
}
|
|
@@ -1,117 +0,0 @@
|
|
|
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
|
-
import { EventNormalizer } from './EventNormalizer';
|
|
10
|
-
import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
|
|
11
|
-
|
|
12
|
-
export class SESNormalizer implements EventNormalizer {
|
|
13
|
-
normalize(webhook: WebhookPayload): EmailEvent {
|
|
14
|
-
const payload = webhook.payload as Record<string, unknown>;
|
|
15
|
-
const message = JSON.parse(payload.Message as string) as Record<string, unknown>;
|
|
16
|
-
const eventType = message.eventType as string;
|
|
17
|
-
|
|
18
|
-
return {
|
|
19
|
-
id: this.generateEventId(message),
|
|
20
|
-
emailId: this.extractMessageId(message),
|
|
21
|
-
messageId: this.extractMessageId(message),
|
|
22
|
-
type: this.mapEventType(eventType),
|
|
23
|
-
recipient: this.extractRecipient(message),
|
|
24
|
-
timestamp: new Date((message.mail as Record<string, unknown>).timestamp as string),
|
|
25
|
-
provider: EmailProvider.AWS_SES,
|
|
26
|
-
metadata: {
|
|
27
|
-
bounceType: this.extractBounceType(message),
|
|
28
|
-
bounceReason: this.extractBounceReason(message),
|
|
29
|
-
complaintFeedbackType: this.extractComplaintType(message),
|
|
30
|
-
url: this.extractClickUrl(message),
|
|
31
|
-
ipAddress: this.extractIpAddress(message),
|
|
32
|
-
userAgent: this.extractUserAgent(message)
|
|
33
|
-
},
|
|
34
|
-
rawEvent: message
|
|
35
|
-
};
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
private mapEventType(sesEvent: string): EmailEventType {
|
|
39
|
-
const mapping: Record<string, EmailEventType> = {
|
|
40
|
-
'Delivery': EmailEventType.DELIVERED,
|
|
41
|
-
'Open': EmailEventType.OPENED,
|
|
42
|
-
'Click': EmailEventType.CLICKED,
|
|
43
|
-
'Bounce': EmailEventType.BOUNCED,
|
|
44
|
-
'Complaint': EmailEventType.COMPLAINED,
|
|
45
|
-
'Reject': EmailEventType.FAILED
|
|
46
|
-
};
|
|
47
|
-
return mapping[sesEvent] || EmailEventType.FAILED;
|
|
48
|
-
}
|
|
49
|
-
|
|
50
|
-
private extractMessageId(message: Record<string, unknown>): string {
|
|
51
|
-
const mail = message.mail as Record<string, unknown>;
|
|
52
|
-
return (mail?.messageId as string) || '';
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
private extractRecipient(message: Record<string, unknown>): string {
|
|
56
|
-
const bounce = message.bounce as Record<string, unknown> | undefined;
|
|
57
|
-
const complaint = message.complaint as Record<string, unknown> | undefined;
|
|
58
|
-
const mail = message.mail as Record<string, unknown>;
|
|
59
|
-
|
|
60
|
-
if (bounce) {
|
|
61
|
-
const bouncedRecipients = bounce.bouncedRecipients as Array<Record<string, string>> | undefined;
|
|
62
|
-
if (bouncedRecipients?.[0]?.emailAddress) {
|
|
63
|
-
return bouncedRecipients[0].emailAddress;
|
|
64
|
-
}
|
|
65
|
-
}
|
|
66
|
-
|
|
67
|
-
if (complaint) {
|
|
68
|
-
const complainedRecipients = complaint.complainedRecipients as Array<Record<string, string>> | undefined;
|
|
69
|
-
if (complainedRecipients?.[0]?.emailAddress) {
|
|
70
|
-
return complainedRecipients[0].emailAddress;
|
|
71
|
-
}
|
|
72
|
-
}
|
|
73
|
-
|
|
74
|
-
const destination = mail.destination as string[] | undefined;
|
|
75
|
-
return destination?.[0] || '';
|
|
76
|
-
}
|
|
77
|
-
|
|
78
|
-
private extractBounceType(message: Record<string, unknown>): 'hard' | 'soft' | undefined {
|
|
79
|
-
const bounce = message.bounce as Record<string, unknown> | undefined;
|
|
80
|
-
if (!bounce) return undefined;
|
|
81
|
-
return (bounce.bounceType as string)?.toLowerCase() as 'hard' | 'soft' | undefined;
|
|
82
|
-
}
|
|
83
|
-
|
|
84
|
-
private extractBounceReason(message: Record<string, unknown>): string | undefined {
|
|
85
|
-
const bounce = message.bounce as Record<string, unknown> | undefined;
|
|
86
|
-
if (!bounce) return undefined;
|
|
87
|
-
const bouncedRecipients = bounce.bouncedRecipients as Array<Record<string, string>> | undefined;
|
|
88
|
-
return bouncedRecipients?.[0]?.diagnosticCode;
|
|
89
|
-
}
|
|
90
|
-
|
|
91
|
-
private extractComplaintType(message: Record<string, unknown>): string | undefined {
|
|
92
|
-
const complaint = message.complaint as Record<string, unknown> | undefined;
|
|
93
|
-
return complaint?.complaintFeedbackType as string | undefined;
|
|
94
|
-
}
|
|
95
|
-
|
|
96
|
-
private extractClickUrl(message: Record<string, unknown>): string | undefined {
|
|
97
|
-
const click = message.click as Record<string, unknown> | undefined;
|
|
98
|
-
return click?.link as string | undefined;
|
|
99
|
-
}
|
|
100
|
-
|
|
101
|
-
private extractIpAddress(message: Record<string, unknown>): string | undefined {
|
|
102
|
-
const open = message.open as Record<string, unknown> | undefined;
|
|
103
|
-
const click = message.click as Record<string, unknown> | undefined;
|
|
104
|
-
return (open?.ipAddress as string) || (click?.ipAddress as string) || undefined;
|
|
105
|
-
}
|
|
106
|
-
|
|
107
|
-
private extractUserAgent(message: Record<string, unknown>): string | undefined {
|
|
108
|
-
const open = message.open as Record<string, unknown> | undefined;
|
|
109
|
-
const click = message.click as Record<string, unknown> | undefined;
|
|
110
|
-
return (open?.userAgent as string) || (click?.userAgent as string) || undefined;
|
|
111
|
-
}
|
|
112
|
-
|
|
113
|
-
private generateEventId(message: Record<string, unknown>): string {
|
|
114
|
-
const mail = message.mail as Record<string, unknown>;
|
|
115
|
-
return `ses-${(mail?.messageId as string) || ''}-${Date.now()}`;
|
|
116
|
-
}
|
|
117
|
-
}
|
|
@@ -1,54 +0,0 @@
|
|
|
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
|
-
import { EventNormalizer } from './EventNormalizer';
|
|
10
|
-
import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
|
|
11
|
-
|
|
12
|
-
export class SMTP2GONormalizer implements EventNormalizer {
|
|
13
|
-
normalize(webhook: WebhookPayload): EmailEvent {
|
|
14
|
-
const event = webhook.payload as Record<string, unknown>;
|
|
15
|
-
|
|
16
|
-
return {
|
|
17
|
-
id: this.generateEventId(event),
|
|
18
|
-
emailId: (event.email_id as string) || (event.message_id as string) || '',
|
|
19
|
-
messageId: (event.message_id as string) || '',
|
|
20
|
-
type: this.mapEventType(event.event as string),
|
|
21
|
-
recipient: (event.rcpt_to as string) || '',
|
|
22
|
-
timestamp: new Date(event.timestamp as string),
|
|
23
|
-
provider: EmailProvider.SMTP2GO,
|
|
24
|
-
metadata: {
|
|
25
|
-
bounceType: this.mapBounceType(event.bounce_type as string | undefined),
|
|
26
|
-
bounceReason: event.reason as string | undefined,
|
|
27
|
-
failureReason: event.reason as string | undefined
|
|
28
|
-
},
|
|
29
|
-
rawEvent: event
|
|
30
|
-
};
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
private mapEventType(smtp2goEvent: string): EmailEventType {
|
|
34
|
-
const mapping: Record<string, EmailEventType> = {
|
|
35
|
-
'delivered': EmailEventType.DELIVERED,
|
|
36
|
-
'open': EmailEventType.OPENED,
|
|
37
|
-
'click': EmailEventType.CLICKED,
|
|
38
|
-
'bounce': EmailEventType.BOUNCED,
|
|
39
|
-
'failed': EmailEventType.FAILED
|
|
40
|
-
};
|
|
41
|
-
return mapping[smtp2goEvent] || EmailEventType.FAILED;
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
private mapBounceType(bounceType?: string): 'hard' | 'soft' | undefined {
|
|
45
|
-
if (!bounceType) return undefined;
|
|
46
|
-
if (bounceType.toLowerCase().includes('hard')) return 'hard';
|
|
47
|
-
if (bounceType.toLowerCase().includes('soft')) return 'soft';
|
|
48
|
-
return undefined;
|
|
49
|
-
}
|
|
50
|
-
|
|
51
|
-
private generateEventId(event: Record<string, unknown>): string {
|
|
52
|
-
return `smtp2go-${(event.message_id as string) || ''}-${Date.now()}`;
|
|
53
|
-
}
|
|
54
|
-
}
|
|
@@ -1,63 +0,0 @@
|
|
|
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
|
-
import { EventNormalizer } from './EventNormalizer';
|
|
10
|
-
import { EmailEvent, EmailEventType, EmailProvider, WebhookPayload } from '../types';
|
|
11
|
-
|
|
12
|
-
export class SendGridNormalizer implements EventNormalizer {
|
|
13
|
-
normalize(webhook: WebhookPayload): EmailEvent {
|
|
14
|
-
const event = webhook.payload as Record<string, unknown>;
|
|
15
|
-
|
|
16
|
-
return {
|
|
17
|
-
id: this.generateEventId(event),
|
|
18
|
-
emailId: (event.email_id as string) || (event.sg_message_id as string) || '',
|
|
19
|
-
messageId: (event.sg_message_id as string) || '',
|
|
20
|
-
type: this.mapEventType(event.event as string),
|
|
21
|
-
recipient: (event.email as string) || '',
|
|
22
|
-
timestamp: new Date((event.timestamp as number) * 1000),
|
|
23
|
-
provider: EmailProvider.SENDGRID,
|
|
24
|
-
metadata: {
|
|
25
|
-
url: event.url as string | undefined,
|
|
26
|
-
bounceType: event.event === 'bounce'
|
|
27
|
-
? ((event.status as string)?.startsWith('5') ? 'hard' : 'soft')
|
|
28
|
-
: undefined,
|
|
29
|
-
bounceReason: event.reason as string | undefined,
|
|
30
|
-
userAgent: event.useragent as string | undefined,
|
|
31
|
-
ipAddress: event.ip as string | undefined,
|
|
32
|
-
deviceType: this.detectDeviceType(event.useragent as string | undefined)
|
|
33
|
-
},
|
|
34
|
-
rawEvent: event
|
|
35
|
-
};
|
|
36
|
-
}
|
|
37
|
-
|
|
38
|
-
private mapEventType(sendgridEvent: string): EmailEventType {
|
|
39
|
-
const mapping: Record<string, EmailEventType> = {
|
|
40
|
-
'delivered': EmailEventType.DELIVERED,
|
|
41
|
-
'open': EmailEventType.OPENED,
|
|
42
|
-
'click': EmailEventType.CLICKED,
|
|
43
|
-
'bounce': EmailEventType.BOUNCED,
|
|
44
|
-
'dropped': EmailEventType.DROPPED,
|
|
45
|
-
'spamreport': EmailEventType.COMPLAINED,
|
|
46
|
-
'unsubscribe': EmailEventType.UNSUBSCRIBED,
|
|
47
|
-
'deferred': EmailEventType.DEFERRED
|
|
48
|
-
};
|
|
49
|
-
return mapping[sendgridEvent] || EmailEventType.FAILED;
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
private generateEventId(event: Record<string, unknown>): string {
|
|
53
|
-
return `sendgrid-${(event.sg_event_id as string) || Date.now()}`;
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
private detectDeviceType(userAgent?: string): 'desktop' | 'mobile' | 'tablet' | 'unknown' {
|
|
57
|
-
if (!userAgent) return 'unknown';
|
|
58
|
-
const ua = userAgent.toLowerCase();
|
|
59
|
-
if (ua.includes('mobile')) return 'mobile';
|
|
60
|
-
if (ua.includes('tablet') || ua.includes('ipad')) return 'tablet';
|
|
61
|
-
return 'desktop';
|
|
62
|
-
}
|
|
63
|
-
}
|
|
@@ -1,68 +0,0 @@
|
|
|
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
|
-
import { PersistenceAdapter } from './PersistenceAdapter';
|
|
10
|
-
import { EmailEvent, EventQuery } from '../types';
|
|
11
|
-
|
|
12
|
-
export class InMemoryPersistenceAdapter implements PersistenceAdapter {
|
|
13
|
-
private events: EmailEvent[] = [];
|
|
14
|
-
private sentEmails: unknown[] = [];
|
|
15
|
-
|
|
16
|
-
async saveEvent(event: EmailEvent): Promise<void> {
|
|
17
|
-
this.events.push(event);
|
|
18
|
-
}
|
|
19
|
-
|
|
20
|
-
async queryEvents(query: EventQuery): Promise<EmailEvent[]> {
|
|
21
|
-
let results = [...this.events];
|
|
22
|
-
|
|
23
|
-
if (query.emailId) {
|
|
24
|
-
results = results.filter(e => e.emailId === query.emailId);
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
if (query.recipient) {
|
|
28
|
-
results = results.filter(e => e.recipient === query.recipient);
|
|
29
|
-
}
|
|
30
|
-
|
|
31
|
-
if (query.eventTypes && query.eventTypes.length > 0) {
|
|
32
|
-
results = results.filter(e => query.eventTypes!.includes(e.type));
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
if (query.startDate) {
|
|
36
|
-
results = results.filter(e => e.timestamp >= query.startDate!);
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
if (query.endDate) {
|
|
40
|
-
results = results.filter(e => e.timestamp <= query.endDate!);
|
|
41
|
-
}
|
|
42
|
-
|
|
43
|
-
// Apply offset and limit
|
|
44
|
-
if (query.offset) {
|
|
45
|
-
results = results.slice(query.offset);
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
if (query.limit) {
|
|
49
|
-
results = results.slice(0, query.limit);
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
return results;
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
async saveSentEmail(emailData: unknown): Promise<void> {
|
|
56
|
-
this.sentEmails.push(emailData);
|
|
57
|
-
}
|
|
58
|
-
|
|
59
|
-
// Test helper methods
|
|
60
|
-
getEventCount(): number {
|
|
61
|
-
return this.events.length;
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
clearEvents(): void {
|
|
65
|
-
this.events = [];
|
|
66
|
-
this.sentEmails = [];
|
|
67
|
-
}
|
|
68
|
-
}
|
|
@@ -1,15 +0,0 @@
|
|
|
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
|
-
import { EmailEvent, EventQuery } from '../types';
|
|
10
|
-
|
|
11
|
-
export interface PersistenceAdapter {
|
|
12
|
-
saveEvent(event: EmailEvent): Promise<void>;
|
|
13
|
-
queryEvents(query: EventQuery): Promise<EmailEvent[]>;
|
|
14
|
-
saveSentEmail?(emailData: unknown): Promise<void>;
|
|
15
|
-
}
|
package/src/types.ts
DELETED
|
@@ -1,261 +0,0 @@
|
|
|
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
|
-
// Unified email event format
|
|
10
|
-
export interface EmailEvent {
|
|
11
|
-
// Event identification
|
|
12
|
-
id: string;
|
|
13
|
-
emailId: string;
|
|
14
|
-
messageId: string;
|
|
15
|
-
|
|
16
|
-
// Event type
|
|
17
|
-
type: EmailEventType;
|
|
18
|
-
|
|
19
|
-
// Recipient information
|
|
20
|
-
recipient: string;
|
|
21
|
-
|
|
22
|
-
// Timestamp
|
|
23
|
-
timestamp: Date;
|
|
24
|
-
|
|
25
|
-
// Provider information
|
|
26
|
-
provider: EmailProvider;
|
|
27
|
-
|
|
28
|
-
// Event-specific data
|
|
29
|
-
metadata: EmailEventMetadata;
|
|
30
|
-
|
|
31
|
-
// Original webhook data (for debugging)
|
|
32
|
-
rawEvent?: unknown;
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
export enum EmailEventType {
|
|
36
|
-
DELIVERED = 'delivered',
|
|
37
|
-
OPENED = 'opened',
|
|
38
|
-
CLICKED = 'clicked',
|
|
39
|
-
BOUNCED = 'bounced',
|
|
40
|
-
COMPLAINED = 'complained',
|
|
41
|
-
UNSUBSCRIBED = 'unsubscribed',
|
|
42
|
-
FAILED = 'failed',
|
|
43
|
-
DEFERRED = 'deferred',
|
|
44
|
-
DROPPED = 'dropped'
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
export enum EmailProvider {
|
|
48
|
-
SENDGRID = 'sendgrid',
|
|
49
|
-
MAILGUN = 'mailgun',
|
|
50
|
-
AWS_SES = 'aws_ses',
|
|
51
|
-
POSTMARK = 'postmark',
|
|
52
|
-
SMTP2GO = 'smtp2go',
|
|
53
|
-
GENERIC_SMTP = 'generic_smtp',
|
|
54
|
-
MANDRILL = 'mandrill',
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
export interface EmailEventMetadata {
|
|
58
|
-
// For clicked events
|
|
59
|
-
url?: string;
|
|
60
|
-
linkId?: string;
|
|
61
|
-
|
|
62
|
-
// For bounced events
|
|
63
|
-
bounceType?: 'hard' | 'soft';
|
|
64
|
-
bounceReason?: string;
|
|
65
|
-
bounceCode?: string;
|
|
66
|
-
|
|
67
|
-
// For complained events
|
|
68
|
-
complaintFeedbackType?: string;
|
|
69
|
-
|
|
70
|
-
// For failed events
|
|
71
|
-
failureReason?: string;
|
|
72
|
-
smtpResponse?: string;
|
|
73
|
-
|
|
74
|
-
// For deferred events
|
|
75
|
-
deferralReason?: string;
|
|
76
|
-
attemptNumber?: number;
|
|
77
|
-
nextAttempt?: Date;
|
|
78
|
-
|
|
79
|
-
// Common metadata
|
|
80
|
-
userAgent?: string;
|
|
81
|
-
ipAddress?: string;
|
|
82
|
-
deviceType?: 'desktop' | 'mobile' | 'tablet' | 'unknown';
|
|
83
|
-
location?: {
|
|
84
|
-
country?: string;
|
|
85
|
-
region?: string;
|
|
86
|
-
city?: string;
|
|
87
|
-
};
|
|
88
|
-
}
|
|
89
|
-
|
|
90
|
-
// Analytics aggregation
|
|
91
|
-
export interface EmailAnalytics {
|
|
92
|
-
// Time range
|
|
93
|
-
startDate: Date;
|
|
94
|
-
endDate: Date;
|
|
95
|
-
|
|
96
|
-
// Counts
|
|
97
|
-
totalSent: number;
|
|
98
|
-
totalDelivered: number;
|
|
99
|
-
totalOpened: number;
|
|
100
|
-
totalClicked: number;
|
|
101
|
-
totalBounced: number;
|
|
102
|
-
totalComplained: number;
|
|
103
|
-
totalUnsubscribed: number;
|
|
104
|
-
totalFailed: number;
|
|
105
|
-
|
|
106
|
-
// Rates
|
|
107
|
-
deliveryRate: number;
|
|
108
|
-
openRate: number;
|
|
109
|
-
clickRate: number;
|
|
110
|
-
clickToOpenRate: number;
|
|
111
|
-
bounceRate: number;
|
|
112
|
-
complaintRate: number;
|
|
113
|
-
unsubscribeRate: number;
|
|
114
|
-
|
|
115
|
-
// Breakdowns
|
|
116
|
-
byProvider: Record<EmailProvider, ProviderAnalytics>;
|
|
117
|
-
byEventType: Record<EmailEventType, number>;
|
|
118
|
-
byBounceType?: {
|
|
119
|
-
hard: number;
|
|
120
|
-
soft: number;
|
|
121
|
-
};
|
|
122
|
-
|
|
123
|
-
// Top links (for clicked events)
|
|
124
|
-
topLinks?: Array<{
|
|
125
|
-
url: string;
|
|
126
|
-
clicks: number;
|
|
127
|
-
uniqueClicks: number;
|
|
128
|
-
}>;
|
|
129
|
-
|
|
130
|
-
// Device breakdown
|
|
131
|
-
byDevice?: {
|
|
132
|
-
desktop: number;
|
|
133
|
-
mobile: number;
|
|
134
|
-
tablet: number;
|
|
135
|
-
unknown: number;
|
|
136
|
-
};
|
|
137
|
-
}
|
|
138
|
-
|
|
139
|
-
export interface ProviderAnalytics {
|
|
140
|
-
sent: number;
|
|
141
|
-
delivered: number;
|
|
142
|
-
opened: number;
|
|
143
|
-
clicked: number;
|
|
144
|
-
bounced: number;
|
|
145
|
-
complained: number;
|
|
146
|
-
failed: number;
|
|
147
|
-
deliveryRate: number;
|
|
148
|
-
openRate: number;
|
|
149
|
-
clickRate: number;
|
|
150
|
-
}
|
|
151
|
-
|
|
152
|
-
// Event callback hooks
|
|
153
|
-
export interface WebhookEventCallbacks {
|
|
154
|
-
readonly onBounce?: (event: EmailEvent) => void | Promise<void>;
|
|
155
|
-
readonly onComplaint?: (event: EmailEvent) => void | Promise<void>;
|
|
156
|
-
readonly onUnsubscribe?: (event: EmailEvent) => void | Promise<void>;
|
|
157
|
-
readonly onDelivery?: (event: EmailEvent) => void | Promise<void>;
|
|
158
|
-
readonly onOpen?: (event: EmailEvent) => void | Promise<void>;
|
|
159
|
-
readonly onClick?: (event: EmailEvent) => void | Promise<void>;
|
|
160
|
-
readonly onFailure?: (event: EmailEvent) => void | Promise<void>;
|
|
161
|
-
}
|
|
162
|
-
|
|
163
|
-
// Configuration
|
|
164
|
-
export interface EmailWebhookEventsConfig {
|
|
165
|
-
// Provider configurations
|
|
166
|
-
providers: ProviderWebhookConfig[];
|
|
167
|
-
|
|
168
|
-
// Event persistence
|
|
169
|
-
persistence?: {
|
|
170
|
-
enabled: boolean;
|
|
171
|
-
adapter: 'supabase' | 'postgresql' | 'mongodb' | 'memory';
|
|
172
|
-
config?: unknown;
|
|
173
|
-
};
|
|
174
|
-
|
|
175
|
-
// Analytics
|
|
176
|
-
analytics?: {
|
|
177
|
-
realTimeEnabled: boolean;
|
|
178
|
-
aggregationInterval: number;
|
|
179
|
-
retentionDays: number;
|
|
180
|
-
};
|
|
181
|
-
|
|
182
|
-
// Notifications
|
|
183
|
-
notifications?: {
|
|
184
|
-
enabled: boolean;
|
|
185
|
-
criticalEvents: EmailEventType[];
|
|
186
|
-
channels: NotificationChannel[];
|
|
187
|
-
};
|
|
188
|
-
|
|
189
|
-
// Event callbacks
|
|
190
|
-
callbacks?: WebhookEventCallbacks;
|
|
191
|
-
|
|
192
|
-
// Rate limiting
|
|
193
|
-
rateLimiting?: {
|
|
194
|
-
enabled: boolean;
|
|
195
|
-
maxEventsPerSecond: number;
|
|
196
|
-
};
|
|
197
|
-
}
|
|
198
|
-
|
|
199
|
-
export interface ProviderWebhookConfig {
|
|
200
|
-
provider: EmailProvider;
|
|
201
|
-
enabled: boolean;
|
|
202
|
-
webhookUrl: string;
|
|
203
|
-
secretKey: string;
|
|
204
|
-
signatureHeader: string;
|
|
205
|
-
signatureAlgorithm: 'sha256' | 'sha1' | 'sha512';
|
|
206
|
-
}
|
|
207
|
-
|
|
208
|
-
export interface NotificationChannel {
|
|
209
|
-
type: 'neverhub' | 'webhook' | 'email';
|
|
210
|
-
config: {
|
|
211
|
-
url?: string;
|
|
212
|
-
recipients?: string[];
|
|
213
|
-
[key: string]: unknown;
|
|
214
|
-
};
|
|
215
|
-
}
|
|
216
|
-
|
|
217
|
-
export interface EmailWebhookResult {
|
|
218
|
-
success: boolean;
|
|
219
|
-
event?: EmailEvent;
|
|
220
|
-
error?: string;
|
|
221
|
-
}
|
|
222
|
-
|
|
223
|
-
export interface WebhookPayload {
|
|
224
|
-
provider: EmailProvider;
|
|
225
|
-
signature: string;
|
|
226
|
-
payload: unknown;
|
|
227
|
-
headers: Record<string, string>;
|
|
228
|
-
}
|
|
229
|
-
|
|
230
|
-
export interface AnalyticsFilters {
|
|
231
|
-
provider?: EmailProvider;
|
|
232
|
-
emailId?: string;
|
|
233
|
-
recipient?: string;
|
|
234
|
-
eventTypes?: EmailEventType[];
|
|
235
|
-
}
|
|
236
|
-
|
|
237
|
-
export interface EventQuery {
|
|
238
|
-
emailId?: string;
|
|
239
|
-
recipient?: string;
|
|
240
|
-
eventTypes?: EmailEventType[];
|
|
241
|
-
startDate?: Date;
|
|
242
|
-
endDate?: Date;
|
|
243
|
-
limit?: number;
|
|
244
|
-
offset?: number;
|
|
245
|
-
}
|
|
246
|
-
|
|
247
|
-
export interface EmailWebhookError {
|
|
248
|
-
code: EmailWebhookErrorCode;
|
|
249
|
-
message: string;
|
|
250
|
-
details?: unknown;
|
|
251
|
-
retryable: boolean;
|
|
252
|
-
}
|
|
253
|
-
|
|
254
|
-
export enum EmailWebhookErrorCode {
|
|
255
|
-
INVALID_SIGNATURE = 'INVALID_SIGNATURE',
|
|
256
|
-
UNSUPPORTED_PROVIDER = 'UNSUPPORTED_PROVIDER',
|
|
257
|
-
NORMALIZATION_FAILED = 'NORMALIZATION_FAILED',
|
|
258
|
-
PERSISTENCE_FAILED = 'PERSISTENCE_FAILED',
|
|
259
|
-
ANALYTICS_UPDATE_FAILED = 'ANALYTICS_UPDATE_FAILED',
|
|
260
|
-
NOTIFICATION_FAILED = 'NOTIFICATION_FAILED'
|
|
261
|
-
}
|
package/tsconfig.json
DELETED
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"compilerOptions": {
|
|
3
|
-
"target": "ES2020",
|
|
4
|
-
"module": "commonjs",
|
|
5
|
-
"lib": ["ES2020"],
|
|
6
|
-
"outDir": "./dist",
|
|
7
|
-
"rootDir": "./src",
|
|
8
|
-
"declaration": true,
|
|
9
|
-
"declarationMap": true,
|
|
10
|
-
"sourceMap": true,
|
|
11
|
-
"strict": true,
|
|
12
|
-
"esModuleInterop": true,
|
|
13
|
-
"skipLibCheck": true,
|
|
14
|
-
"forceConsistentCasingInFileNames": true,
|
|
15
|
-
"resolveJsonModule": true,
|
|
16
|
-
"moduleResolution": "node",
|
|
17
|
-
"noImplicitAny": true,
|
|
18
|
-
"strictNullChecks": true,
|
|
19
|
-
"strictFunctionTypes": true,
|
|
20
|
-
"strictBindCallApply": true,
|
|
21
|
-
"strictPropertyInitialization": true,
|
|
22
|
-
"noImplicitThis": true,
|
|
23
|
-
"alwaysStrict": true,
|
|
24
|
-
"noUnusedLocals": true,
|
|
25
|
-
"noUnusedParameters": true,
|
|
26
|
-
"noImplicitReturns": true,
|
|
27
|
-
"noFallthroughCasesInSwitch": true
|
|
28
|
-
},
|
|
29
|
-
"include": ["src/**/*"],
|
|
30
|
-
"exclude": ["node_modules", "dist", "__tests__"]
|
|
31
|
-
}
|