@memberjunction/communication-gmail 2.42.1 → 2.44.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.
Files changed (2) hide show
  1. package/README.md +250 -0
  2. package/package.json +4 -4
package/README.md ADDED
@@ -0,0 +1,250 @@
1
+ # @memberjunction/communication-gmail
2
+
3
+ Gmail/Google Suite provider implementation for the MemberJunction Communication framework. This package enables sending and receiving emails through Gmail's API using OAuth2 authentication.
4
+
5
+ ## Overview
6
+
7
+ The Gmail Communication Provider integrates Gmail's API with MemberJunction's communication infrastructure, providing:
8
+
9
+ - Email sending capabilities with full HTML and plain text support
10
+ - Email retrieval with flexible query options
11
+ - Reply-to-message functionality maintaining thread context
12
+ - Message forwarding capabilities
13
+ - OAuth2-based authentication using refresh tokens
14
+ - Automatic token refresh for uninterrupted service
15
+
16
+ ## Installation
17
+
18
+ ```bash
19
+ npm install @memberjunction/communication-gmail
20
+ ```
21
+
22
+ ## Configuration
23
+
24
+ The Gmail provider requires OAuth2 credentials and a refresh token. Set the following environment variables:
25
+
26
+ ```env
27
+ # Required: OAuth2 Client Credentials
28
+ GMAIL_CLIENT_ID=your_client_id_here
29
+ GMAIL_CLIENT_SECRET=your_client_secret_here
30
+ GMAIL_REDIRECT_URI=your_redirect_uri_here
31
+ GMAIL_REFRESH_TOKEN=your_refresh_token_here
32
+
33
+ # Optional: Default sender email
34
+ GMAIL_SERVICE_ACCOUNT_EMAIL=noreply@yourdomain.com
35
+ ```
36
+
37
+ ### Obtaining OAuth2 Credentials
38
+
39
+ 1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
40
+ 2. Create a new project or select an existing one
41
+ 3. Enable the Gmail API for your project
42
+ 4. Create OAuth2 credentials (OAuth 2.0 Client ID)
43
+ 5. Set up the OAuth consent screen
44
+ 6. Use the OAuth2 flow to obtain a refresh token with the required scopes
45
+
46
+ ### Required OAuth2 Scopes
47
+
48
+ The provider requires the following Gmail API scopes:
49
+ - `https://www.googleapis.com/auth/gmail.send`
50
+ - `https://www.googleapis.com/auth/gmail.readonly`
51
+ - `https://www.googleapis.com/auth/gmail.modify`
52
+ - `https://www.googleapis.com/auth/gmail.compose`
53
+
54
+ ## Usage
55
+
56
+ ### Basic Setup
57
+
58
+ ```typescript
59
+ import { GmailProvider } from '@memberjunction/communication-gmail';
60
+
61
+ // The provider is automatically registered with MemberJunction's class factory
62
+ // using the @RegisterClass decorator
63
+ ```
64
+
65
+ ### Sending Emails
66
+
67
+ ```typescript
68
+ import { ProcessedMessage, MessageResult } from '@memberjunction/communication-types';
69
+ import { GmailProvider } from '@memberjunction/communication-gmail';
70
+
71
+ const provider = new GmailProvider();
72
+
73
+ const message: ProcessedMessage = {
74
+ To: 'recipient@example.com',
75
+ From: 'sender@example.com', // Optional, uses authenticated account if not specified
76
+ FromName: 'Sender Name',
77
+ ProcessedSubject: 'Test Email',
78
+ ProcessedBody: 'This is a plain text email body',
79
+ ProcessedHTMLBody: '<html><body><h1>This is an HTML email</h1></body></html>',
80
+ CCRecipients: ['cc@example.com'],
81
+ BCCRecipients: ['bcc@example.com']
82
+ };
83
+
84
+ const result: MessageResult = await provider.SendSingleMessage(message);
85
+
86
+ if (result.Success) {
87
+ console.log('Email sent successfully');
88
+ } else {
89
+ console.error('Failed to send email:', result.Error);
90
+ }
91
+ ```
92
+
93
+ ### Retrieving Messages
94
+
95
+ ```typescript
96
+ import { GetMessagesParams, GetMessagesResult } from '@memberjunction/communication-types';
97
+
98
+ const params: GetMessagesParams = {
99
+ NumMessages: 10,
100
+ UnreadOnly: true,
101
+ ContextData: {
102
+ query: 'from:important@example.com', // Gmail search query
103
+ MarkAsRead: true // Mark retrieved messages as read
104
+ }
105
+ };
106
+
107
+ const result: GetMessagesResult = await provider.GetMessages(params);
108
+
109
+ if (result.Success) {
110
+ result.Messages.forEach(message => {
111
+ console.log(`From: ${message.From}`);
112
+ console.log(`Subject: ${message.Subject}`);
113
+ console.log(`Body: ${message.Body}`);
114
+ });
115
+ } else {
116
+ console.error('Failed to get messages:', result.ErrorMessage);
117
+ }
118
+ ```
119
+
120
+ ### Replying to Messages
121
+
122
+ ```typescript
123
+ import { ReplyToMessageParams, ProcessedMessage } from '@memberjunction/communication-types';
124
+
125
+ const replyMessage: ProcessedMessage = {
126
+ To: 'original-sender@example.com',
127
+ ProcessedSubject: 'Re: Original Subject',
128
+ ProcessedBody: 'This is my reply'
129
+ };
130
+
131
+ const params: ReplyToMessageParams = {
132
+ MessageID: 'original-message-id', // Gmail message ID
133
+ Message: replyMessage
134
+ };
135
+
136
+ const result = await provider.ReplyToMessage(params);
137
+
138
+ if (result.Success) {
139
+ console.log('Reply sent successfully');
140
+ }
141
+ ```
142
+
143
+ ### Forwarding Messages
144
+
145
+ ```typescript
146
+ import { ForwardMessageParams } from '@memberjunction/communication-types';
147
+
148
+ const params: ForwardMessageParams = {
149
+ MessageID: 'message-to-forward-id',
150
+ ToRecipients: ['forward-to@example.com'],
151
+ CCRecipients: ['cc@example.com'],
152
+ BCCRecipients: ['bcc@example.com'],
153
+ Message: 'FYI - forwarding this message' // Optional forward comment
154
+ };
155
+
156
+ const result = await provider.ForwardMessage(params);
157
+
158
+ if (result.Success) {
159
+ console.log('Message forwarded successfully');
160
+ }
161
+ ```
162
+
163
+ ## API Reference
164
+
165
+ ### GmailProvider Class
166
+
167
+ The main provider class that extends `BaseCommunicationProvider` from `@memberjunction/communication-types`.
168
+
169
+ #### Methods
170
+
171
+ ##### `SendSingleMessage(message: ProcessedMessage): Promise<MessageResult>`
172
+ Sends a single email message through Gmail.
173
+
174
+ ##### `GetMessages(params: GetMessagesParams): Promise<GetMessagesResult>`
175
+ Retrieves messages from Gmail based on the provided parameters.
176
+
177
+ ##### `ReplyToMessage(params: ReplyToMessageParams): Promise<ReplyToMessageResult>`
178
+ Replies to an existing Gmail message, maintaining the thread context.
179
+
180
+ ##### `ForwardMessage(params: ForwardMessageParams): Promise<ForwardMessageResult>`
181
+ Forwards an existing Gmail message to new recipients.
182
+
183
+ ### Configuration Module
184
+
185
+ #### Environment Variables
186
+ - `GMAIL_CLIENT_ID` (required): OAuth2 client ID
187
+ - `GMAIL_CLIENT_SECRET` (required): OAuth2 client secret
188
+ - `GMAIL_REDIRECT_URI` (required): OAuth2 redirect URI
189
+ - `GMAIL_REFRESH_TOKEN` (required): OAuth2 refresh token
190
+ - `GMAIL_SERVICE_ACCOUNT_EMAIL` (optional): Default sender email address
191
+
192
+ ### Authentication Module
193
+
194
+ The `auth.ts` module exports:
195
+ - `GmailClient`: Pre-configured Gmail API client
196
+ - `getAuthenticatedUser()`: Helper function to verify authentication
197
+
198
+ ## Integration with MemberJunction
199
+
200
+ This provider integrates seamlessly with MemberJunction's communication framework:
201
+
202
+ 1. **Automatic Registration**: The provider is automatically registered using the `@RegisterClass` decorator
203
+ 2. **Type Safety**: Full TypeScript support with types from `@memberjunction/communication-types`
204
+ 3. **Logging**: Integrated with MemberJunction's logging system via `@memberjunction/core`
205
+ 4. **Global Registry**: Utilizes `@memberjunction/global` for class registration
206
+
207
+ ## Dependencies
208
+
209
+ - `@memberjunction/communication-types`: Communication framework interfaces and types
210
+ - `@memberjunction/core`: Core MemberJunction utilities and logging
211
+ - `@memberjunction/global`: Global class registry system
212
+ - `googleapis`: Google APIs Node.js client library
213
+ - `dotenv`: Environment variable management
214
+ - `env-var`: Environment variable validation
215
+
216
+ ## Error Handling
217
+
218
+ The provider includes comprehensive error handling:
219
+ - OAuth2 authentication failures
220
+ - API rate limiting
221
+ - Network errors
222
+ - Invalid message formats
223
+ - Missing required fields
224
+
225
+ All errors are logged using MemberJunction's logging system and returned with descriptive error messages.
226
+
227
+ ## Security Considerations
228
+
229
+ 1. **Refresh Token Security**: Store refresh tokens securely and never commit them to version control
230
+ 2. **Scope Limitations**: Request only the minimum required OAuth2 scopes
231
+ 3. **Environment Variables**: Use secure methods to manage environment variables in production
232
+ 4. **API Credentials**: Regularly rotate client secrets and monitor API usage
233
+
234
+ ## Development
235
+
236
+ ### Building
237
+
238
+ ```bash
239
+ npm run build
240
+ ```
241
+
242
+ ### Cleaning
243
+
244
+ ```bash
245
+ npm run clean
246
+ ```
247
+
248
+ ## License
249
+
250
+ This package is part of the MemberJunction ecosystem. See the root repository for license information.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memberjunction/communication-gmail",
3
- "version": "2.42.1",
3
+ "version": "2.44.0",
4
4
  "description": "Gmail/Google Suite provider for MemberJunction Communication framework",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -12,9 +12,9 @@
12
12
  "clean": "rimraf dist"
13
13
  },
14
14
  "dependencies": {
15
- "@memberjunction/communication-types": "2.42.1",
16
- "@memberjunction/core": "2.42.1",
17
- "@memberjunction/global": "2.42.1",
15
+ "@memberjunction/communication-types": "2.44.0",
16
+ "@memberjunction/core": "2.44.0",
17
+ "@memberjunction/global": "2.44.0",
18
18
  "dotenv": "^16.3.1",
19
19
  "env-var": "^7.4.1",
20
20
  "googleapis": "^130.0.0"