Skip to content

Commit dad53e8

Browse files
thinkingseriousthinkingserious
authored
Merge pull request #407 from adamreisnz/monorepo
Monorepo
2 parents c29a5c4 + 6be583e commit dad53e8

File tree

100 files changed

+22145
-16133
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

100 files changed

+22145
-16133
lines changed

‎.gitignore

+6-9
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,8 @@
1-
node_modules/
2-
npm-debug.log
31
.DS_Store
2+
coverage/
3+
node_modules/
44
test/config.js
5-
.env.test
6-
.env.development
7-
.env.production
8-
.env.staging
9-
.env
10-
temp.js
11-
.vscode/
5+
.env*
6+
*.log
7+
.vscode/
8+
prism_darwin_amd64

‎.travis.yml

+7-3
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,22 @@
11
language: node_js
22
node_js:
3-
- "4"
43
- "6"
54
- "7"
5+
- "8"
66
before_install:
77
- npm install -g npm@2
88
before_script:
99
- mkdir prism
1010
- mkdir prism/bin
1111
- export PATH=$PATH:$PWD/prism/bin/
1212
- ./test/prism.sh
13+
- yarn prism &
14+
- sleep 5 # give it some time to start
1315
script:
14-
- npm test
15-
- npm run test:typescript
16+
- lerna bootstrap
17+
- yarn test:mail
18+
- yarn test:client
19+
- yarn test:helpers
1620
notifications:
1721
hipchat:
1822
rooms:

‎CONTRIBUTING.md

+10-24
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ We welcome direct contributions to the sendgrid-nodejs code base. Thank you!
6464

6565
##### Prerequisites #####
6666

67-
- Node.js version 4, 6 or 7
67+
- Node.js version 6, 7 or 8
6868
- Please see [package.json](https://github.com/sendgrid/sendgrid-nodejs/tree/master/package.json)
6969

7070
##### Initial setup: #####
@@ -79,7 +79,7 @@ npm install
7979

8080
First, get your free SendGrid account [here](https://sendgrid.com/free?source=sendgrid-nodejs).
8181

82-
You will need to setup the following environment to use the SendGrid example:
82+
You will need to setup the following environment to use the SendGrid examples in the README.md, USAGE.md and USE_CASES.md files:
8383

8484
```
8585
echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
@@ -89,17 +89,15 @@ source ./sendgrid.env
8989

9090
##### Execute: #####
9191

92-
See the [examples folder](https://github.com/sendgrid/sendgrid-nodejs/tree/master/examples) to get started quickly.
93-
9492
To run an example:
9593

9694
```bash
9795
touch example.js
9896
```
9997

100-
Copy the desired example into `example.js`.
98+
Copy the desired code into `example.js`. For this example, I'm assuming you create this file in the root of this project.
10199

102-
Change the path to the Sendgrid library to `./lib/sendgrid.js`.
100+
Change the path to the Sendgrid library to the reletive path, for example: `./packages/mail/mail`.
103101

104102
```
105103
node example.js
@@ -108,32 +106,20 @@ node example.js
108106
<a name="understanding_the_codebase"></a>
109107
## Understanding the Code Base
110108

111-
**/examples**
112-
113-
Working examples that demonstrate usage.
114-
115-
**/tests**
116-
117-
Tests for the SendGrid object.
118-
119-
**/lib**
120-
121-
The interface to the SendGrid API.
109+
This repo is organized as a monorepo with the packages residing in the `./packages` directory. Please see the root [README.md](https://github.com/sendgrid/sendgrid-nodejs/blob/master/README.md) for details.
122110

123111
<a name="testing"></a>
124112
## Testing
125113

126114
All PRs require passing tests before the PR will be reviewed.
127115

128-
All test files are in the [`tests`](https://github.com/sendgrid/sendgrid-nodejs/tree/master/test) directory.
116+
To run tests, please install Prism first by either running `yarn prism:install` or manually downloading from (the Prism website)[https://stoplight.io/platform/prism/].
129117

130-
For the purposes of contributing to this repo, please update the [`test.js`](https://github.com/sendgrid/sendgrid-nodejs/tree/master/test/test.js) file with unit tests as you modify the code.
118+
Next, start Prism in one console window using `yarn prism`.
131119

132-
Run the tests at the root of the `sendgrid-nodejs` repo:
120+
Open a new console window and run `lerna bootstrap`.
133121

134-
```bash
135-
mocha
136-
```
122+
And finally, run `yarn test`, or specific tests e.g. `yarn test:mail` or `yarn test:client`.
137123

138124
<a name="style_guidelines_and_naming_conventions"></a>
139125
## Style Guidelines & Naming Conventions
@@ -144,7 +130,7 @@ Generally, we follow the style guidelines as suggested by the official language.
144130

145131
Please run your code through:
146132

147-
- [ESLint](http://eslint.org/) with the tandard style guide.
133+
- [ESLint](http://eslint.org/) with the standard style guide.
148134

149135
## Creating a Pull Request<a name="creating_a_pull_request"></a>
150136

‎LICENSE.txt ‎LICENSE.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright (c) 2012-2016 SendGrid, Inc.
1+
Copyright (c) 2012-2017 SendGrid, Inc.
22

33
Permission is hereby granted, free of charge, to any person obtaining
44
a copy of this software and associated documentation files (the

‎README.md

+14-180
Original file line numberDiff line numberDiff line change
@@ -2,206 +2,40 @@
22
[![npm version](https://badge.fury.io/js/sendgrid.svg)](https://badge.fury.io/js/sendgrid)
33
[![Email Notifications Badge](https://dx.sendgrid.com/badge/nodejs)](https://dx.sendgrid.com/newsletter/nodejs)
44

5-
**NEW:** Subscribe to email [notifications](https://dx.sendgrid.com/newsletter/nodejs) for releases and breaking changes.
6-
75
**This library allows you to quickly and easily use the SendGrid Web API v3 via Node.js.**
86

9-
Version 3.X.X+ of this library provides full support for all SendGrid [Web API v3](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html) endpoints, including the new [v3 /mail/send](https://sendgrid.com/blog/introducing-v3mailsend-sendgrids-new-mail-endpoint).
7+
We want this library to be community driven and SendGrid led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/sendgrid/sendgrid-nodejs/issues) and [pull requests](https://github.com/sendgrid/sendgrid-nodejs/blob/master/CONTRIBUTING.md) or simply upvote or comment on existing issues or pull requests.
108

11-
This library represents the beginning of a new path for SendGrid. We want this library to be community driven and SendGrid led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/sendgrid/sendgrid-nodejs/issues) and [pull requests](https://github.com/sendgrid/sendgrid-nodejs/blob/master/CONTRIBUTING.md) or simply upvote or comment on existing issues or pull requests.
9+
To be notified when this package is updated, please subscribe to email [notifications](https://dx.sendgrid.com/newsletter/nodejs) for releases and breaking changes.
1210

1311
Please browse the rest of this README for further detail.
1412

1513
We appreciate your continued support, thank you!
1614

1715
# Table of Contents
1816

19-
* [Installation](#installation)
20-
* [Quick Start](#quick_start)
21-
* [Usage](#usage)
22-
* [Use Cases](#use_cases)
17+
* [Introduction - Please Read First](#introduction)
18+
* [Additional Documentation](#usage)
2319
* [Announcements](#announcements)
2420
* [Roadmap](#roadmap)
2521
* [How to Contribute](#contribute)
2622
* [Troubleshooting](#troubleshooting)
2723
* [About](#about)
2824

29-
<a name="installation"></a>
30-
# Installation
31-
32-
## Prerequisites
33-
34-
- Node.js version 4, 6 or 7
35-
- The SendGrid service, starting at the [free level](https://sendgrid.com/free?source=sendgrid-nodejs)
36-
37-
## Setup Environment Variables
38-
39-
Update the development environment with your [SENDGRID_API_KEY](https://app.sendgrid.com/settings/api_keys), for example:
40-
41-
```bash
42-
echo "export SENDGRID_API_KEY='YOUR_API_KEY'" > sendgrid.env
43-
echo "sendgrid.env" >> .gitignore
44-
source ./sendgrid.env
45-
```
46-
47-
## Install Package
48-
49-
The following recommended installation requires [npm](https://npmjs.org/). If you are unfamiliar with npm, see the [npm docs](https://npmjs.org/doc/). Npm comes installed with Node.js since node version 0.8.x therefore you likely already have it.
50-
51-
```bash
52-
npm install --save sendgrid
53-
```
54-
55-
## Dependencies
56-
57-
- [Nodejs-HTTP-Client](https://github.com/sendgrid/nodejs-http-client)
58-
59-
<a name="quick_start"></a>
60-
# Quick Start
61-
62-
## Hello Email
63-
64-
The following is the minimum needed code to send an email with the [/mail/send Helper](https://github.com/sendgrid/sendgrid-nodejs/tree/master/lib/helpers/mail) ([here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/examples/helpers/mail/example.js#L15) is a full example):
65-
66-
### With Mail Helper Class
67-
68-
```javascript
69-
var helper = require('sendgrid').mail;
70-
var fromEmail = new helper.Email('[email protected]');
71-
var toEmail = new helper.Email('[email protected]');
72-
var subject = 'Sending with SendGrid is Fun';
73-
var content = new helper.Content('text/plain', 'and easy to do anywhere, even with Node.js');
74-
var mail = new helper.Mail(fromEmail, subject, toEmail, content);
75-
76-
var sg = require('sendgrid')(process.env.SENDGRID_API_KEY);
77-
var request = sg.emptyRequest({
78-
method: 'POST',
79-
path: '/v3/mail/send',
80-
body: mail.toJSON()
81-
});
82-
83-
sg.API(request, function (error, response) {
84-
if (error) {
85-
console.log('Error response received');
86-
}
87-
console.log(response.statusCode);
88-
console.log(response.body);
89-
console.log(response.headers);
90-
});
91-
```
92-
93-
The `Mail` constructor creates a [personalization object](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/personalizations.html) for you. [Here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/examples/helpers/mail/example.js#L10) is an example of how to add to it.
94-
95-
### Without Mail Helper Class
96-
97-
The following is the minimum needed code to send an email without the /mail/send Helper ([here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/examples/mail/mail.js#L31) is a full example):
98-
99-
```javascript
100-
var sg = require('sendgrid')(process.env.SENDGRID_API_KEY);
101-
var request = sg.emptyRequest({
102-
method: 'POST',
103-
path: '/v3/mail/send',
104-
body: {
105-
personalizations: [
106-
{
107-
to: [
108-
{
109-
email: '[email protected]'
110-
}
111-
],
112-
subject: 'Sending with SendGrid is Fun'
113-
}
114-
],
115-
from: {
116-
email: '[email protected]'
117-
},
118-
content: [
119-
{
120-
type: 'text/plain',
121-
value: 'and easy to do anywhere, even with Node.js'
122-
}
123-
]
124-
}
125-
});
126-
127-
// With promise
128-
sg.API(request)
129-
.then(function (response) {
130-
console.log(response.statusCode);
131-
console.log(response.body);
132-
console.log(response.headers);
133-
})
134-
.catch(function (error) {
135-
// error is an instance of SendGridError
136-
// The full response is attached to error.response
137-
console.log(error.response.statusCode);
138-
});
139-
140-
// With callback
141-
sg.API(request, function (error, response) {
142-
if (error) {
143-
console.log('Error response received');
144-
}
145-
console.log(response.statusCode);
146-
console.log(response.body);
147-
console.log(response.headers);
148-
});
149-
```
150-
151-
## General v3 Web API Usage
152-
153-
```javascript
154-
var sg = require('sendgrid')(process.env.SENDGRID_API_KEY);
155-
156-
// GET Collection
157-
var request = sg.emptyRequest({
158-
method: 'GET',
159-
path: '/v3/api_keys'
160-
});
161-
162-
// With promise
163-
sg.API(request)
164-
.then(function (response) {
165-
console.log(response.statusCode);
166-
console.log(response.body);
167-
console.log(response.headers);
168-
})
169-
.catch(function (error) {
170-
// error is an instance of SendGridError
171-
// The full response is attached to error.response
172-
console.log(error.response.statusCode);
173-
});
174-
175-
// With callback
176-
sg.API(request, function (error, response) {
177-
if (error) {
178-
console.log('Error response received');
179-
}
180-
console.log(response.statusCode);
181-
console.log(response.body);
182-
console.log(response.headers);
183-
});
184-
```
185-
186-
<a name="usage"></a>
187-
# Usage
188-
189-
- [SendGrid Docs](https://sendgrid.com/docs/API_Reference/Web_API_v3/index.html)
190-
- [Library Usage Docs](https://github.com/sendgrid/sendgrid-nodejs/blob/master/USAGE.md)
191-
- [Example Code](https://github.com/sendgrid/sendgrid-nodejs/tree/master/examples)
192-
- [How-to: Migration from v2 to v3](https://sendgrid.com/docs/Classroom/Send/v3_Mail_Send/how_to_migrate_from_v2_to_v3_mail_send.html)
193-
- [v3 Web API Mail Send Helper](https://github.com/sendgrid/sendgrid-nodejs/tree/master/lib/helpers/mail/README.md)
194-
195-
<a name="use_cases"></a>
196-
# Use Cases
197-
198-
[Examples of common API use cases](https://github.com/sendgrid/sendgrid-nodejs/blob/master/USE_CASES.md), such as how to send an email with a transactional template.
25+
<a name="introduction"></a>
26+
# Introduction
27+
28+
This library is broken up into several packages as a monorepo so that you only need to install the packages necessary for your use case. This README contains information pertaining to all packages.
29+
30+
* [@sendgrid/mail](https://github.com/sendgrid/sendgrid-nodejs/tree/master/packages/mail) - if you just want to send email
31+
* [@sendgrid/client](https://github.com/sendgrid/sendgrid-nodejs/tree/master/packages/client) - to use all other [SendGrid v3 Web API endpoints](https://sendgrid.com/docs/API_Reference/api_v3.html)
32+
* [@sendgrid/inbound-mail-parser](https://github.com/sendgrid/sendgrid-nodejs/tree/master/packages/inbound-mail-parser) - help with parsing the SendGrid Inbound Parse API
33+
* [@sendgrid/contact-import](https://github.com/sendgrid/sendgrid-nodejs/tree/master/packages/contact-import) - help with importing contacts into the ContactDB
34+
* [@sendgrid/helpers](https://github.com/sendgrid/sendgrid-nodejs/tree/master/packages/helpers) - a collection of classes and helpers used internally by the above packages
19935

20036
<a name="announcements"></a>
20137
# Announcements
20238

203-
Please see our announcement regarding [breaking changes](https://github.com/sendgrid/sendgrid-nodejs/issues/290). Your support is appreciated!
204-
20539
All updates to this library are documented in our [CHANGELOG](https://github.com/sendgrid/sendgrid-nodejs/blob/master/CHANGELOG.md) and [releases](https://github.com/sendgrid/sendgrid-nodejs/releases). You may also subscribe to email [release notifications](https://dx.sendgrid.com/newsletter/nodejs) for releases and breaking changes.
20640

20741
<a name="roadmap"></a>

0 commit comments

Comments
 (0)