@bentonow/bento-node-sdk 0.1.14 → 0.2.1

package/README.md

@@ -11,6 +11,7 @@ Track events, update data, record LTV and more in Node.JS. Data is stored in you
 🐶 Battle-tested by [NativShark](https://nativshark.com) Bento Production (a Bento customer)!
 
 ❤️ Thank you @HelloKashif from [IPInfo](https://ipinfo.io) for your contribution.
+❤️ Thank you @jonsherrard from [Devular](https://www.devular.com/) for your contribution.
 
 - [Installation](#Installation)
 - [Get Started](#Get-Started)
@@ -20,10 +21,12 @@ Track events, update data, record LTV and more in Node.JS. Data is stored in you
     - [addSubscriber(parameters: AddSubscriberParameters): Promise\<boolean\>](#addsubscriberparameters-addsubscriberparameters-promiseboolean)
     - [removeSubscriber(parameters: RemoveSubscriberParameters): Promise\<boolean\>](#removesubscriberparameters-removesubscriberparameters-promiseboolean)
     - [updateFields(parameters: UpdateFieldsParameters\<S\>): Promise\<boolean\>](#updatefieldsparameters-updatefieldsparameterss-promiseboolean)
+    - [track(parameters: TrackParameters<S, E>): Promise<boolean>](#trackparameters-trackparameterss-e-promiseboolean)
     - [trackPurchase(parameters: TrackPurchaseParameters): Promise\<boolean\>](#trackpurchaseparameters-trackpurchaseparameters-promiseboolean)
   - [Batch](#Batch)
     - [.importSubscribers(parameters: BatchImportSubscribersParameter\<S\>): Promise\<number\>](#batchimportsubscribersparameters-batchimportsubscribersparameters-promisenumber)
     - [.importEvents(parameters: BatchImportEventsParameter\<S, E\>): Promise\<number\>](#batchimporteventsparameters-batchimporteventsparameters-e-promisenumber)
+    - [.sendTransactionalEmails(parameters: BatchsendTransactionalEmailsParameter<S, E>): Promise<number>](#batchsendtransactionalemailsparameters-batchsendtransactionalemailsparameters-e-promisenumber)
   - [Commands](#Commands)
     - [.addTag(parameters: AddTagParameters): Promise\<Subscriber\<S\> | null\>](#commandsaddtagparameters-addtagparameters-promisesubscribers--null)
     - [.removeTag(parameters: RemoveTagParameters): Promise\<Subscriber\<S\> | null\>](#commandsremovetagparameters-removetagparameters-promisesubscribers--null)
@@ -64,9 +67,11 @@ Run the following command in your project folder.
 npm install @bentonow/bento-node-sdk --save
 ```
 
-## Get Started
+## Getting Started
 
-To get started with tracking things in Bento, simply initialize the client and run wild!
+To get started with tracking your users in Bento, simply initialize the client and go wild. 
+
+The below example showcases using `track` and `trackPurchase` which are the two recommended functions you should lean on as they can trigger automations. If you need to upload a lot of data but do not wish to trigger automations, like when you sign up, then use [importSubscribers](#batchimportsubscribersparameters-batchimportsubscribersparameters-promisenumber) instead.
 
 ```ts
 import { Analytics } from '@bentonow/bento-node-sdk';
@@ -74,38 +79,35 @@ import { Analytics } from '@bentonow/bento-node-sdk';
 const bento = new Analytics({
   authentication: {
     publishableKey: 'publishableKey',
-    secretKey: 'secretKey',
+    secretKey: 'secretKey', 
   },
   logErrors: false, // Set to true to see the HTTP errors logged
   siteUuid: 'siteUuid',
 });
 
-bento.V1.addSubscriber({
-  email: 'test@bentonow.com',
-})
-  .then(result => console.log(result))
-  .catch(error => console.error(error));
-
-bento.V1.updateFields({
+bento.V1.track({
   email: 'test@bentonow.com',
+  type: '$formSubmitted',
   fields: {
-    firstName: 'Test',
-    lastName: 'User',
+    first_name: 'Test',
+    last_name: 'Test',
   },
-})
-  .then(result => console.log(result))
-  .catch(error => console.error(error));
+  details: {
+    fromCustomEvent: true,
+  },
+}).then(result => console.log(result)).catch(error => console.error(error));
 
 bento.V1.trackPurchase({
   email: 'test@bentonow.com',
   purchaseDetails: {
-    unique: { key: 1234 },
+    unique: { key: 1234 }, // this key stops duplicate order values being tracked
     value: { amount: 100, currency: 'USD' },
   },
   cart: {
-    abandoned_checkout_url: '',
+    abandoned_checkout_url: 'https://example.com',
   },
 });
+
 ```
 
 Read on to see what all you can do with the SDK.
@@ -271,8 +273,8 @@ bento.V1.track({
   email: 'test@bentonow.com',
   type: '$custom.event',
   fields: {
-        firstName: 'Custom Name',
-        lastName: 'Custom Name',
+    firstName: 'Custom Name',
+    lastName: 'Custom Name',
   },
   details: {
     fromCustomEvent: true,
@@ -286,7 +288,7 @@ bento.V1.track({
 
 ### `Batch.importSubscribers(parameters: BatchImportSubscribersParameter<S>): Promise<number>`
 
-**This does not trigger automations!** - If you wish to trigger automations, please batch import events with the type set to `BentoEvents.SUBSCRIBE`, or `$subscribe`. Note that the batch event import cannot attach custom fields and will ignore everything except the email.
+**This does not trigger automations!** - If you wish to trigger automations, please batch import events.
 
 Creates a batch job to import subscribers into the system. You can pass in between 1 and 1,000 subscribers to import. Each subscriber must have an email, and may optionally have any additional fields. The additional fields are added as custom fields on the subscriber.
 
@@ -305,6 +307,8 @@ bento.V1.Batch.importSubscribers({
     },
     {
       email: 'test2@bentonow.com',
+      some_custom_variable: 'tester-123',
+      primary_user: true,
     },
     {
       email: 'test3@bentonow.com',
@@ -320,7 +324,7 @@ bento.V1.Batch.importSubscribers({
 
 ### `Batch.importEvents(parameters: BatchImportEventsParameter<S, E>): Promise<number>`
 
-Creates a batch job to import events into the system. You can pass in between 1 and 1,000 events to import. Each event must have an email and a type. In addition to this, you my pass in additional data in the `details` property,
+Creates a batch job to import events into the system. You can pass in between 1 and 100 events to import. Each event must have an email and a type. In addition to this, you my pass in additional data in the `details` property,
 
 Returns the number of events that were imported.
 
@@ -364,6 +368,37 @@ bento.V1.Batch.importEvents({
   .catch(error => console.error(error));
 ```
 
+---
+
+### `Batch.sendTransactionalEmails(parameters: BatchsendTransactionalEmailsParameter<S, E>): Promise<number>`
+
+Creates a batch job to send transactional emails from Bento's infrastructure. You can pass in between 1 and 100 emails to send. Each email must have a `to` address, a `from` address, a `subject`, an `html_body` and `transactional: true`.
+
+In addition you can add a `personalizations` object to provide liquid tags that will be injected into the email.
+
+Requests are instant and queued into a priority queue. Most requests will be processed within 30 seconds. We currently limit this endpoint to 60 emails per minute.
+
+Returns the number of emails that were imported.
+
+```ts
+bento.V1.Batch.sendTransactionalEmails({
+  emails: [
+    {
+      to: 'test@bentonow.com', // required — if no user with this email exists in your account they will be created.
+      from: 'jesse@bentonow.com', // required — must be an email author in your account.
+      subject: 'Reset Password', // required
+      html_body: '<p>Here is a link to reset your password ... {{ link }}</p>', // required - can also use text_body if you want to use our plain text theme.
+      transactional: true, // IMPORTANT — this bypasses the subscription status of a user. Abuse will lead to account shutdown.
+      personalizations: {
+        link: 'https://example.com/test',
+      }, // optional — provide your own Liquid tags to be injected into the email.
+    },
+  ],
+})
+  .then(result => console.log(result))
+  .catch(error => console.error(error));
+```
+
 ## Commands
 
 ### `Commands.addTag(parameters: AddTagParameters): Promise<Subscriber<S> | null>`