patramail 0.1.0 → 0.1.1

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 +87 -86
  2. package/package.json +9 -1
package/README.md CHANGED
@@ -1,74 +1,89 @@
1
+ <div align="center">
2
+
1
3
  # PatraMail
2
4
 
3
- PatraMail generates responsive HTML and plain text for transactional emails from
4
- one JavaScript object. It runs on Node.js 18+ using CommonJS and zero runtime
5
- dependencies. Pass the output to your existing email transport.
5
+ **Transactional emails from a JavaScript object.**
6
+
7
+ Responsive HTML and matching plain text for account emails, events, receipts, and your own messages.
8
+
9
+ [![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-285747)](https://nodejs.org/)
10
+ [![Zero runtime dependencies](https://img.shields.io/badge/runtime_dependencies-0-52406e)](package.json)
11
+ [![MIT license](https://img.shields.io/badge/license-MIT-365677)](LICENSE)
12
+
13
+ [GitHub repository](https://github.com/sarthak-gupta229/patramail) · [Quick start](#quick-start) · [Templates](#templates) · [Custom emails](#build-a-custom-email) · [API reference](https://github.com/sarthak-gupta229/patramail/blob/main/docs/api.md)
14
+
15
+ </div>
16
+
17
+ ![The PatraMail event invitation in light and dark themes](https://raw.githubusercontent.com/sarthak-gupta229/patramail/main/docs/events-preview.png)
18
+
19
+ ## Quick start
6
20
 
7
21
  ```sh
8
22
  npm install patramail
9
23
  ```
10
24
 
11
- ## Quick start
25
+ Generate a password-reset email from an action URL supplied by your app.
12
26
 
13
27
  ```js
14
28
  const PatraMail = require('patramail');
15
-
16
- const mailGenerator = new PatraMail({
17
- theme: 'default',
18
- product: {
19
- name: 'Acme',
20
- link: 'https://acme.test',
21
- },
29
+ const mailer = new PatraMail({
30
+ product: { name: 'Acme', link: 'https://acme.test' },
22
31
  });
23
32
 
24
- const email = {
25
- body: {
26
- name: 'Jane',
27
- intro: 'Welcome to Acme! Your account is ready.',
28
- action: {
29
- instructions: 'Confirm your email address to get started.',
30
- button: {
31
- color: '#1746a2',
32
- text: 'Confirm your account',
33
- link: 'https://acme.test/confirm?token=example',
34
- },
35
- },
36
- outro: 'If you have questions, reply to this email.',
37
- },
38
- };
33
+ const email = PatraMail.templates.passwordReset({
34
+ recipient: 'Jane',
35
+ link: 'https://acme.test/reset?token=example',
36
+ });
39
37
 
40
- const emailBody = mailGenerator.generate(email);
41
- const emailText = mailGenerator.generatePlaintext(email);
38
+ const html = mailer.generate(email);
39
+ const text = mailer.generatePlaintext(email);
42
40
 
43
- require('node:fs').writeFileSync('preview.html', emailBody, 'utf8');
41
+ require('node:fs').writeFileSync('preview.html', html, 'utf8');
44
42
  ```
45
43
 
46
- Open `preview.html` in a browser, or pass `emailBody` and `emailText` to your
47
- email transport.
44
+ Open `preview.html` in a browser. PatraMail generates the content. Your email
45
+ transport handles delivery. For both formats and the subject and preheader in
46
+ one call, use the [named `PatraMail` constructor](https://github.com/sarthak-gupta229/patramail/blob/main/docs/api.md).
48
47
 
49
- ![Password-reset email preview showing the heading, reset button, and footer](docs/password-reset.png)
48
+ ## Templates
49
+
50
+ | Password reset | Email verification |
51
+ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
52
+ | ![Password-reset email with a Reset password button](https://raw.githubusercontent.com/sarthak-gupta229/patramail/main/docs/password-reset.png) | ![Verification email with a Verify email address button](https://raw.githubusercontent.com/sarthak-gupta229/patramail/main/docs/email-verification.png) |
53
+
54
+ | Account templates | Event templates |
55
+ | ------------------------------------------ | -------------------------------------------- |
56
+ | `passwordReset` · Reset password | `invitation` · Collect RSVPs |
57
+ | `emailVerification` · Verify email address | `confirmation` · Confirm a registration |
58
+ | `dashboardWelcome` · Go to dashboard | `reminder` · Send details before the event |
59
+ | | `update` · Announce a change |
60
+ | | `cancellation` · Notify attendees |
61
+ | | `followUp` · Share resources after the event |
62
+
63
+ Account templates take an action URL from your app. Event templates can include
64
+ a date, location, and action button. All nine generate HTML and plain text.
65
+ [Account template options](https://github.com/sarthak-gupta229/patramail/blob/main/docs/api.md#account-templates) · [Event template options](https://github.com/sarthak-gupta229/patramail/blob/main/docs/events.md)
50
66
 
51
67
  ## Build a custom email
52
68
 
53
- Pass your own `body` to `generate()`. You can set the heading, write
54
- multiple paragraphs, add one or more buttons, and include footer links.
55
- Use a theme object to set your brand color and other styling.
69
+ Pass your own `body` to create a message from scratch. The default constructor
70
+ supports the Mailgen-style `body.action`, `generate()`, and
71
+ `generatePlaintext()` workflow. Choose the built-in light or dark theme,
72
+ or pass custom colors and typography.
56
73
 
57
74
  ```js
58
75
  const PatraMail = require('patramail');
59
76
  const mailer = new PatraMail({
60
- theme: { brand: '#30564b', radius: '8px' },
61
77
  product: { name: 'Acme', link: 'https://acme.test' },
78
+ theme: { brand: '#30564b', radius: '8px' },
62
79
  });
63
80
 
64
81
  const email = {
65
- subject: 'Your monthly statement is ready',
66
- preheader: 'Review your statement and billing settings.',
67
82
  body: {
68
83
  title: 'Your statement is ready',
69
84
  intro: [
70
85
  'Your monthly statement is available.',
71
- 'You can view or download it in your account.',
86
+ 'View or download it in your account.',
72
87
  ],
73
88
  action: [
74
89
  {
@@ -90,71 +105,57 @@ const html = mailer.generate(email);
90
105
  const text = mailer.generatePlaintext(email);
91
106
  ```
92
107
 
93
- See the [Mailgen-style API](docs/api.md#mailgen-style-usage),
94
- [input schema](docs/input-schema.md), and [theme options](docs/themes.md).
95
-
96
- ## Account and event templates
97
-
98
- Use `templates.passwordReset`, `templates.emailVerification`, or
99
- `templates.dashboardWelcome` for common account emails. Each accepts the
100
- action URL from your application and generates matching HTML and text.
101
- See the [account template example](docs/api.md#account-templates).
102
-
103
- Choose from invitation, registration confirmation, reminder, event update,
104
- cancellation, and follow-up templates. Each supplies event copy, a color
105
- palette, and an optional action button. See the
106
- [event template guide](docs/events.md) for a complete example.
107
-
108
- Use `const { PatraMail } = require('patramail')` when you want the
109
- combined `{ html, text, subject, preheader }` result in one call.
110
- See the [API reference](docs/api.md).
108
+ Add a preheader, product logo, or receipt table using the [input schema](https://github.com/sarthak-gupta229/patramail/blob/main/docs/input-schema.md).
109
+ PatraMail escapes user content by default and validates action URLs.
110
+ [Theme options](https://github.com/sarthak-gupta229/patramail/blob/main/docs/themes.md) · [Mailgen-style API](https://github.com/sarthak-gupta229/patramail/blob/main/docs/api.md#mailgen-style-usage)
111
111
 
112
112
  ## Send with Nodemailer
113
113
 
114
- Install Nodemailer in your application with `npm install nodemailer`. Copy the
115
- quick start into an async function, then use the generated HTML and text with your SMTP settings.
114
+ Install Nodemailer with `npm install nodemailer`. Pass the generated content
115
+ to your transport inside an async function.
116
116
 
117
117
  ```js
118
118
  const nodemailer = require('nodemailer');
119
+
119
120
  const transport = nodemailer.createTransport(process.env.SMTP_URL);
120
121
  await transport.sendMail({
121
122
  from: process.env.MAIL_FROM,
122
123
  to: process.env.MAIL_TO,
123
- subject: 'Confirm your Acme account',
124
- html: emailBody,
125
- text: emailText,
124
+ subject: 'Reset your Acme password',
125
+ html,
126
+ text,
126
127
  });
127
128
  ```
128
129
 
129
- Set `SMTP_URL` to your provider's SMTP URL and set `MAIL_FROM` and `MAIL_TO`
130
- to your sender and recipient addresses.
130
+ Set `SMTP_URL`, `MAIL_FROM`, and `MAIL_TO` for your provider.
131
+ The [runnable Nodemailer example](https://github.com/sarthak-gupta229/patramail/blob/main/examples/with-nodemailer.js) can also print
132
+ a complete MIME message locally.
131
133
 
132
- ## Examples and reference
134
+ ## Preview and develop
133
135
 
134
- - [Mailgen-style quick start](examples/mailgen-style/index.js) writes a local HTML preview and prints the plain-text version.
135
- - [Password reset](examples/password-reset.js) and [receipt](examples/receipt.js) print HTML when run with Node.
136
- - [Nodemailer example](examples/with-nodemailer.js) emits a complete MIME message to stdout with Nodemailer installed. Set `SMTP_URL`, `MAIL_FROM`, and `MAIL_TO` to send it using your SMTP provider.
137
- - `npm run preview` in this repository generates the example HTML files under `preview/`.
138
- - [API reference](docs/api.md), [input schema](docs/input-schema.md), and [themes](docs/themes.md).
136
+ ```sh
137
+ npm ci
138
+ npm run preview
139
+ npm test
140
+ npm run lint
141
+ ```
139
142
 
140
- ## Email-client compatibility
143
+ Open the generated files in `preview/`. The repository also includes runnable
144
+ [account](https://github.com/sarthak-gupta229/patramail/blob/main/examples/account.js), [event](https://github.com/sarthak-gupta229/patramail/blob/main/examples/events.js),
145
+ [receipt](https://github.com/sarthak-gupta229/patramail/blob/main/examples/receipt.js), and [Mailgen-style](https://github.com/sarthak-gupta229/patramail/blob/main/examples/mailgen-style/index.js)
146
+ examples. To update HTML snapshots intentionally, run
147
+ `UPDATE_SNAPSHOTS=1 npm test` and review the diffs.
141
148
 
142
- Chrome previews verified desktop light and dark layouts and a 375px receipt
143
- with a horizontally scrolling table. The browser preview is useful for layout
144
- checks. Inbox verification is still pending for Gmail, Outlook desktop and web,
145
- Apple Mail, and a mobile email client.
149
+ <details>
150
+ <summary>Email-client compatibility</summary>
146
151
 
147
- - Classic Outlook may display square corners and use the inline fallback colors.
148
- Dark-mode recoloring varies by client. [Can I email dark mode results](https://www.caniemail.com/features/css-at-media-prefers-color-scheme/)
149
- - Some clients may ignore the receipt's scrolling wrapper or clip a wide table.
150
- Keep transactional tables narrow when targeting those clients. [Can I email overflow results](https://www.caniemail.com/features/css-overflow/)
152
+ Chrome previews verified desktop light and dark layouts and the 375px receipt
153
+ layout. Real inbox verification is pending for Gmail, Outlook, Apple Mail,
154
+ and mobile email clients.
151
155
 
152
- For a transport smoke test, [Ethereal](https://ethereal.email/) catches messages
153
- in a free SMTP sandbox. For an inbox check, send to accounts you control or use
154
- a service that renders the supported clients.
156
+ Classic Outlook may show square corners. Dark-mode recoloring and wide-table
157
+ scrolling vary by client. [Dark-mode support](https://www.caniemail.com/features/css-at-media-prefers-color-scheme/) · [Overflow support](https://www.caniemail.com/features/css-overflow/)
155
158
 
156
- ## Development
159
+ </details>
157
160
 
158
- Run `npm ci`, `npm test`, and `npm run lint`. When changing the generated
159
- markup intentionally, run `UPDATE_SNAPSHOTS=1 npm test` and review the
160
- resulting diffs in `test/snapshots/`.
161
+ [Changelog](https://github.com/sarthak-gupta229/patramail/blob/main/CHANGELOG.md) · [MIT License](https://github.com/sarthak-gupta229/patramail/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "patramail",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Generate transactional email HTML and plain text from structured input",
5
5
  "main": "src/index.js",
6
6
  "scripts": {
@@ -20,5 +20,13 @@
20
20
  "devDependencies": {
21
21
  "eslint": "8.57.1",
22
22
  "prettier": "3.8.5"
23
+ },
24
+ "repository": {
25
+ "type": "git",
26
+ "url": "git+https://github.com/sarthak-gupta229/patramail.git"
27
+ },
28
+ "homepage": "https://github.com/sarthak-gupta229/patramail#readme",
29
+ "bugs": {
30
+ "url": "https://github.com/sarthak-gupta229/patramail/issues"
23
31
  }
24
32
  }