		{
		"name": "@splitmedialabs/supermailer-node",
		"description": "Node JS library for Supermailer.",
		"version": "1.0.3",
		"version": "2.0.0",
		"license": "MIT",
		@@ -6,0 +6,0 @@ "repository": "https://github.com/SplitmediaLabsLimited/supermailer-node",

204

README.md


		# Supermailer Node
		This library gives you the methods you need to interact with Supermailer's API. You can manage recipients, send emails and retrieve logs.

		# Installation
		Node 8+ required

		```
		npm install @splitmedialabs/supermailer-node --save
		# or with yarn
		yarn add @splitmedialabs/supermailer-node
		```

		# Configuration
		This is the structure of the configuration object you need pass to Supermailer's constructor:

		```js
		const config = {
		apiKey: 'put-your-api-key-here',
		apiUrl: 'supermailer.splitmedialabs.com',
		namespace: 'xsplit'
		}
		```

		Properties:
		- apiKey: `String` (required) An API key you get from supermailer.splitmedialabs.com/settings to authenticate your requests.
		- apiUrl: `String` (required) The base url of the Supermailer API.
		- namespace: `String` (required) The namespace your service is operating on.

		# Usage

		## Initialization
		Before using the library, you need to initialize it with a config object:

		```js
		const config = require('path/to/your/config/file');
		const Supermailer = require('@splitmedialabs/supermailer-node');
		const SM = new Supermailer(config);
		```

		## Quick examples
		These examples are only for quick reference. Check out the API Reference below for more details on how the library works.

		NOTE: The following examples assume that your Supermailer class is already initialized with a valid configuration object.

		### Creating a recipient
		```js
		// Add the data to the Supermailer data object
		SM.data.addString('email', 'example-email@example.com');
		SM.data.addString('username', 'example-value');

		// Create the recipient
		await SM.recipients.create();
		```

		### Updating a recipient
		```js
		// Add the data to the Supermailer data object
		SM.data.addString('email', 'example-email@example.com'); // This email is gonna update
		SM.data.addDate('date_of_birth', '1988-21-12');

		// Update the recipient
		await SM.recipients.update('current-recipient-email@example.com');
		```

		### Deleting a recipient
		```js
		// Delete the recipient
		await SM.recipients.delete('current-recipient-email@example.com');
		```

		# API Reference

		## Supermailer.data
		Supermailer library uses an implicit data object for the recipient's attributes. This means that you don't need to pass an object in the create and update methods as long as you have populated Supermailer's data object prior to calling create or update.

		NOTE: You need to call Supermailer.recipients.create() or Supermailer.recipients.update() after adding the data, otherwise you are not sending any request to the API.

		### Supermailer.data.addBoolean()
		Validates a `Boolean` value and adds it to the data object.

		```js
		SM.data.addBoolean(name, value);
		```

		Parameters:
		- name: `String` (required) Name of the attribute (ex: user_is_premium).
		- value: `Boolean` (required) Wether or not the user has this attribute (`true` or `false`).

		### Supermailer.data.addDate()
		Validates a date `String` value and adds it to the data object.

		```js
		SM.data.addDate(name, value);
		```

		Parameters:
		- name: `String` (required) Name of the attribute (ex: 'date_of_birth').
		- value: `String` (required) A date string that is parseable by javascript Date.parse() (ex: '1988-12-21' or '1988-12-21T09:54:14.189Z').

		### Supermailer.data.addEvent()
		Generates a UTC ISO date `String` and adds it to the data object .

		```js
		SM.data.addEvent(name);
		```

		Parameters:
		- name: `String` (required) Name of the attribute (ex: 'signup_date').

		### Supermailer.data.addNumber()
		Validates a `Number` value and adds it to the data object.

		```js
		SM.data.addNumber(name, value);
		```

		Parameters:
		- name: `String` (required) Name of the attribute (ex: 'bulk_licenses_count').
		- value: `Integer\|Float` (required) Number value for the attribute (ex: 1 or 2.5).

		### Supermailer.data.addString()
		Validates a `String` value and adds it the data object.

		```js
		SM.data.addString(name, value);
		```

		Parameters:
		- name: `String` (required) Name of the attribute (ex: 'license_name').
		- value: `String` (required) String value for the attribute (ex: 'free').

		## Supermailer.recipients
		Methods for interacting with Supermailer API recipients.

		### Supermailer.recipients.create()
		Creates a recipient after having populated the data object with the data methods.

		```js
		// Add some data to the recipient
		SM.data.addString('email', 'recipient_email@example.com');
		SM.data.addEvent('user_signup');

		// Create the recipient
		SM.recipients.create();
		```

		Parameters: No parameters need to be passed to this method but you need to add at least one `email` attribute when creating new recipient.

		### Supermailer.recipients.update()
		Updates a recipient based on his email after having populated the data object with data methods.

		```js
		// Add some data to the recipient
		SM.data.addString('email', 'new_recipient_email@example.com');
		SM.data.addDate('date_of_birth', '1988-12-21');

		// Update the recipient
		SM.recipients.update('current_recipient_email@example.com');
		```

		Parameters:
		- email: `String` (required) Email of the recipient at the time of update.


		### Supermailer.recipients.delete()
		Deletes a recipient based on his email address.

		```js
		// Delete the recipient
		SM.recipients.delete('current_recipient_email@example.com');
		```

		Parameters:
		- email: `String` (required) Email of the recipient at the time of delete.

		### Supermailer.recipients.log()
		Get the recipient's logs.

		```js
		// Get logs for a recipient
		SM.recipients.logs('current_recipient_email@example.com', 10, 100);
		```

		Parameters:
		- email: `String` (required) Email of the recipient at the time of request.
		- offset: `Integer` (optional, default: 0) Offset to start from when getting the logs.
		- limit: `Integer` (optional, default: 100) Maximum number of log records to return.

		## Supermailer.emails
		Methods for sending emails with Supermailer API recipients.

		### Supermailer.emails.sendTransactional()
		Send a transactional email to a recipient.

		```js
		// Get logs for a recipient
		SM.emails.sendTransactional({
		templateGroup: 'name_of_the_template_group',
		recipientEmail: 'email_to_send_to@example.com'
		});
		```

		Parameters:
		- payload: `Object` (required) Information on the transactional email to send containing at least `templateGroup` and `recipientEmail` properties
		Lots of changes happened, this README is going to be rewritten more accurately.

src/recipients/create.js

		module.exports = async function create() {
		const payload = this.attributes;
		const payload = {
		email: this.email,
		...this.attributes,
		};

		@@ -10,8 +13,2 @@ if (Object.entries(payload).length === 0) {

		if (typeof payload.email !== 'string') {
		throw new Error(
		`You need to set at least the email of type string on the Supermailer data object to create a recipient. Use Supermailer.data.addString('email', 'your_value') to do so.`
		);
		}

		try {
		@@ -18,0 +15,0 @@ const response = await this.api.post(`/api/supermailer/recipients`, payload);

src/recipients/delete.js

+@@ -1,12 +0,4 @@
+module.exports = async function _delete(email) {
+  if (typeof email !== 'string') {
+    throw new Error(
+      `Supermailer.recipients.delete parameter must be the current email of the user and must be a string.`
+    );
+  email = encodeURIComponent(email);
+module.exports = async function _delete() {
+  try {
+    const response = await this.api.delete(`/api/supermailer/recipients/${email}`);
+    const response = await this.api.delete(`/api/supermailer/recipients/${this.email}`);
+    return response.data;
+@@ -13,0 +5,0 @@ } catch (error) {

src/recipients/logs.js

		const qs = require('query-string');

		module.exports = async function logs(email, offset = 0, limit = 100) {
		if (typeof email !== 'string') {
		throw new Error(
		`Supermailer.recipients.logs first parameter must be the current email of the user you want to get the logs for.`
		);
		}
		module.exports = async function logs(offset = 0, limit = 100) {
		const email = this.email;

		@@ -10,0 +6,0 @@ if (typeof offset !== 'number') console.log(`Note: Offset can be passed as second parameter, defaulting to 0...`);

src/recipients/update.js

		@@ -1,2 +0,3 @@
		module.exports = async function update(currentEmail) {
		module.exports = async function update() {
		const currentEmail = this.email;
		const payload = this.attributes;
		@@ -16,6 +17,4 @@

		const email = encodeURIComponent(currentEmail);

		try {
		const response = await this.api.patch(`/api/supermailer/recipients/${email}`, payload);
		const response = await this.api.patch(`/api/supermailer/recipients/${currentEmail}`, payload);
		return response.data;
		@@ -22,0 +21,0 @@ } catch (error) {

src/Supermailer.js

		@@ -0,1 +1,3 @@
		const Recipient = require('./Recipient');

		class Supermailer {
		@@ -14,41 +16,20 @@ constructor(config) {

		// Initialize config object
		this.config = {
		api: {
		key: config.apiKey,
		url: config.apiUrl,
		},
		namespace: config.namespace,
		};
		const api = require('../lib/api').create({
		baseURL: `https://${config.apiUrl}`,
		headers: { 'X-Supermailer-Api-Key': config.apiKey, 'X-Supermailer-Namespace': config.namespace },
		});

		// Initialize api object
		this.api = require('../lib/api').create({
		baseURL: `https://${this.config.api.url}`,
		headers: { 'X-Supermailer-Api-Key': this.config.api.key, 'X-Supermailer-Namespace': this.config.namespace },
		});
		this.api = api;

		// Initialize email methods
		this.email = {
		this.emails = {
		sendTransactional: require('./emails/sendTransactional').bind(this),
		};

		// Initialize recipients methods
		this.recipients = {
		create: require('./recipients/create').bind(this),
		update: require('./recipients/update').bind(this),
		delete: require('./recipients/delete').bind(this),
		logs: require('./recipients/logs').bind(this),
		this.Recipient = function(email) {
		if (typeof email !== 'string')
		throw new Error('You need to pass an email string as the only parameter to this function.');
		return new Recipient({ email, api });
		};

		// Initialize the data methods
		this.data = {
		addBoolean: require('./data/addBoolean').bind(this),
		addDate: require('./data/addDate').bind(this),
		addEvent: require('./data/addEvent').bind(this),
		addNumber: require('./data/addNumber').bind(this),
		addString: require('./data/addString').bind(this),
		};

		// Initialize the attributes object for sending data through the library
		this.attributes = {};
		}
		@@ -55,0 +36,0 @@ }

@splitmedialabs/supermailer-node - npm Package Compare versions

Improved metrics

Worsened metrics