Bento SDK for Node.JS

🍱 Simple, powerful analytics for Node.JS projects!

Track events, update data, record LTV and more in Node.JS. Data is stored in your Bento account so you can easily research and investigate what's going on.

👋 To get personalized support, please tweet @bento or email jesse@bentonow.com!

🐶 Battle-tested by NativShark Bento Production (a Bento customer)!

❤️ Thank you @HelloKashif from IPInfo for your contribution. ❤️ Thank you @jonsherrard from Devular for your contribution.

Installation
Get Started
Modules
Types Reference
TypeScript
- Generics
  - S
  - E
Things to Know
Contributing
License

Installation

Run the following command in your project folder.

npm install @bentonow/bento-node-sdk --save

Getting Started

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 instead.

import { Analytics } from '@bentonow/bento-node-sdk';

const bento = new Analytics({
  authentication: {
    publishableKey: 'publishableKey',
    secretKey: 'secretKey', 
  },
  logErrors: false, // Set to true to see the HTTP errors logged
  siteUuid: 'siteUuid',
});

bento.V1.track({
  email: 'test@bentonow.com',
  type: '$formSubmitted',
  fields: {
    first_name: 'Test',
    last_name: 'Test',
  },
  details: {
    fromCustomEvent: true,
  },
}).then(result => console.log(result)).catch(error => console.error(error));

bento.V1.trackPurchase({
  email: 'test@bentonow.com',
  purchaseDetails: {
    unique: { key: 1234 }, // this key stops duplicate order values being tracked
    value: { amount: 100, currency: 'USD' },
  },
  cart: {
    abandoned_checkout_url: 'https://example.com',
  },
});

Read on to see what all you can do with the SDK.

Modules

In addition to the top-level Analytics object, we also provide access to other parts of the API behind their corresponding modules. You can access these off of the main Analytics object.

The Analytics module also provides access to various versions of the API (currently just V1), and each of those provides access to the corresponding modules documented below.

Analytics (Base Module)

`tagSubscriber(parameters: TagSubscriberParameters): Promise<boolean>`

This TRIGGERS automations! - If you do not wish to trigger automations, please use the Commands.addTag method.

Tags a subscriber with the specified email and tag. If either the tag or the user do not exist, they will be created in the system. If the user already has the tag, another tag event will be sent, triggering any automations that take place upon a tag being added to a subscriber. Please be aware of the potential consequences.

Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.

Returns true if the event was successfully dispatched. Returns false otherwise.

Reference Types: TagSubscriberParameters

bento.V1.tagSubscriber({
  email: 'test@bentonow.com',
  tagName: 'Test Tag',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`addSubscriber(parameters: AddSubscriberParameters<S>): Promise<boolean>`

This TRIGGERS automations! - If you do not wish to trigger automations, please use the Commands.subscribe method.

Creates a subscriber in the system. If the subscriber already exists, another subscribe event will be sent, triggering any automations that take place upon subscription. Please be aware of the potential consequences.

You may optionally pass any fields that you wish to be set on the subscriber during creation.

Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.

Returns true if the event was successfully dispatched. Returns false otherwise.

Reference Types: AddSubscriberParameters<S>

bento.V1.addSubscriber({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

bento.V1.addSubscriber({
  date: new Date('2021-08-20T01:32:57.530Z'),
  email: 'test@bentonow.com',
  fields: {
    firstName: 'Test',
    lastName: 'Subscriber',
  },
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`removeSubscriber(parameters: RemoveSubscriberParameters): Promise<boolean>`

This TRIGGERS automations! - If you do not wish to trigger automations, please use the Commands.unsubscribe method.

Unsubscribes an email in the system. If the email is already unsubscribed, another unsubscribe event will be sent, triggering any automations that take place upon an unsubscribe happening. Please be aware of the potential consequences.

Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.

Returns true if the event was successfully dispatched. Returns false otherwise.

Reference Types: RemoveSubscriberParameters

bento.V1.removeSubscriber({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`updateFields(parameters: UpdateFieldsParameters<S>): Promise<boolean>`

This TRIGGERS automations! - If you do not wish to trigger automations, please use the Commands.addField method.

Sets the passed-in custom fields on the subscriber, creating the subscriber if it does not exist. If the fields are already set on the subscriber, the event will be sent, triggering any automations that take place upon fields being updated. Please be aware of the potential consequences.

Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.

Returns true if the event was successfully dispatched. Returns false otherwise.

Reference Types: UpdateFieldsParameters<S>

bento.V1.updateFields({
  email: 'test@bentonow.com',
  fields: {
    firstName: 'Test',
  },
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`trackPurchase(parameters: TrackPurchaseParameters): Promise<boolean>`

This TRIGGERS automations! - There is no way to achieve this same behavior without triggering automations.

Tracks a purchase in Bento, used to calculate LTV for your subscribers. The values that are received should be numbers, in cents. For example, $1.00 should be 100.

Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.

Returns true if the event was successfully dispatched. Returns false otherwise.

Reference Types: TrackPurchaseParameters

bento.V1.trackPurchase({
  email: 'test@bentonow.com',
  purchaseDetails: {
    unique: {
      key: 1234,
    },
    value: {
      amount: 100,
      currency: 'USD',
    },
  },
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`track(parameters: TrackParameters<S, E>): Promise<boolean>`

This TRIGGERS automations! - There is no way to achieve this same behavior without triggering automations.

Tracks a custom event in Bento.

Because this method uses the batch API, the tag may take between 1 and 3 minutes to appear in the system.

Returns true if the event was successfully dispatched. Returns false otherwise.

Reference Types: TrackParameters<S, E>

bento.V1.track({
  email: 'test@bentonow.com',
  type: '$custom.event',
  fields: {
    firstName: 'Custom Name',
    lastName: 'Custom Name',
  },
  details: {
    fromCustomEvent: true,
  },
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

Batch

`Batch.importSubscribers(parameters: BatchImportSubscribersParameter<S>): Promise<number>`

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.

This method is processed by the Bento import queues and it may take between 1 and 5 minutes for the results to appear in your dashboard.

Returns the number of subscribers that were imported.

Reference Types: BatchImportSubscribersParameter<S>

bento.V1.Batch.importSubscribers({
  subscribers: [
    {
      email: 'test@bentonow.com',
      age: 21,
    },
    {
      email: 'test2@bentonow.com',
      some_custom_variable: 'tester-123',
      primary_user: true,
    },
    {
      email: 'test3@bentonow.com',
      name: 'Test User',
    },
  ],
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`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 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.

Reference Types: BatchImportEventsParameter<S, E>

bento.V1.Batch.importEvents({
  events: [
    {
      email: 'test@bentonow.com',
      type: BentoEvents.SUBSCRIBE,
    },
    {
      email: 'test@bentonow.com',
      type: BentoEvents.UNSUBSCRIBE,
    },
    {
      email: 'test@bentonow.com',
      type: BentoEvents.REMOVE_TAG,
      details: {
        tag: 'tag_to_remove',
      },
    },
    {
      email: 'test@bentonow.com',
      type: BentoEvents.TAG,
      details: {
        tag: 'tag_to_add',
      },
    },
    {
      email: 'test@bentonow.com',
      details: {
        customData: 'Used internally.',
      },
      type: '$custom.myEvent,
    },
  ],
})
  .then(result => console.log(result))
  .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.

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>`

This does not trigger automations! - If you wish to trigger automations, please use the core module's tagSubscriber method.

Adds a tag to the subscriber with the matching email.

Note that both the tag and the subscriber will be created if either is missing from system.

Reference Types: AddTagParameters, Subscriber<S>

bento.V1.Commands.addTag({
  email: 'test@bentonow.com',
  tagName: 'Test Tag',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Commands.removeTag(parameters: RemoveTagParameters): Promise<Subscriber<S> | null>`

Removes the specified tag from the subscriber with the matching email.

Reference Types: RemoveTagParameters, Subscriber<S>

bento.V1.Commands.removeTag({
  email: 'test@bentonow.com',
  tagName: 'Test Tag',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Commands.addField(parameters: AddFieldParameters<S>): Promise<Subscriber<S> | null>`

This does not trigger automations! - If you wish to trigger automations, please use the core module's updateFields method.

Adds a field to the subscriber with the matching email.

Note that both the field and the subscriber will be created if either is missing from system.

Reference Types: AddFieldParameters<S>, Subscriber<S>

bento.V1.Commands.addField({
  email: 'test@bentonow.com',
  field: {
    key: 'testKey',
    value: 'testValue',
  },
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Commands.removeField(parameters: RemoveFieldParameters<S>): Promise<Subscriber<S> | null>`

Removes a field to the subscriber with the matching email.

Reference Types: RemoveFieldParameters<S>, Subscriber<S>

bento.V1.Commands.removeField({
  email: 'test@bentonow.com',
  fieldName: 'testField',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Commands.subscribe(parameters: SubscribeParameters): Promise<Subscriber<S> | null>`

This does not trigger automations! - If you wish to trigger automations, please use the core module's addSubscriber method.

Subscribes the supplied email to Bento. If the email does not exist, it is created.

If the subscriber had previously unsubscribed, they will be re-subscribed.

Reference Types: SubscribeParameters, Subscriber<S>

bento.V1.Commands.subscribe({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Commands.unsubscribe(parameters: UnsubscribeParameters): Promise<Subscriber<S> | null>`

This does not trigger automations! - If you wish to trigger automations, please use the core module's removeSubscriber method.

Unsubscribes the supplied email to Bento. If the email does not exist, it is created and immediately unsubscribed. If they had already unsubscribed, the unsubscribed_at property is updated.

Reference Types: UnsubscribeParameters, Subscriber<S>

bento.V1.Commands.unsubscribe({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Commands.changeEmail(parameters: ChangeEmailParameters): Promise<Subscriber<S> | null>`

Updates the email of a user in Bento.

Reference Types: ChangeEmailParameters, Subscriber<S>

bento.V1.Commands.changeEmail({
  oldEmail: 'test@bentonow.com',
  newEmail: 'new@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

Experimental

`Experimental.validateEmail(parameters: ValidateEmailParameters): Promise<boolean>`

EXPERIMENTAL - This functionality is experimental and may change or stop working at any time.

Attempts to validate the email. You can provide additional information to further refine the validation.

If a name is provided, it compares it against the US Census Data, and so the results may be biased.

Reference Types: ValidateEmailParameters

bento.V1.Experimental.validateEmail({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Experimental.guessGender(parameters: GuessGenderParameters): Promise<GuessGenderResponse>`

EXPERIMENTAL - This functionality is experimental and may change or stop working at any time.

Attempts to guess the gender of the person given a provided name. It compares the name against the US Census Data, and so the results may be biased.

It is possible for the gender to be unknown if the system cannot confidently conclude what gender it may be.

Reference Types: GuessGenderParameters, GuessGenderResponse

bento.V1.Experimental.guessGender({
  name: 'Jesse',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Experimental.geolocate(parameters: GeolocateParameters): Promise<LocationData | null>`

EXPERIMENTAL - This functionality is experimental and may change or stop working at any time.

Attempts to provide location data given a provided IP address.

Reference Types: GeolocateParameters, LocationData

bento.V1.Experimental.geolocate({
  ip: '127.0.0.1',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Experimental.checkBlacklist(parameters: BlacklistParameters): Promise<BlacklistResponse>`

EXPERIMENTAL - This functionality is experimental and may change or stop working at any time.

Looks up the provided URL or IP Address against various blacklists to see if the site has been blacklisted anywhere.

Reference Types: BlacklistParameters, BlacklistResponse

bento.V1.Experimental.checkBlacklist({
  domain: 'bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

Fields

`Fields.getFields(): Promise<Field[] | null>`

Returns all of the fields for the site.

Reference Types: Field

bento.V1.Experimental.validateEmail({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Fields.createField(parameters: CreateFieldParameters): Promise<Field[] | null>`

Creates a field inside of Bento. The name of the field is automatically generated from the key that is passed in upon creation. For example:

Key	Name
`'thisIsAKey'`	`'This Is A Key'`
`'this is a key'`	`'This Is A Key'`
`'this-is-a-key'`	`'This Is A Key'`
`'this_is_a_key'`	`'This Is A Key'`

Reference Types: CreateFieldParameters, Field

bento.V1.Fields.createField({
  key: 'testKey',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

Forms

`Forms.getResponses(formIdentifier: string): Promise<FormResponse[] | null>`

Returns all of the responses for the form with the specified identifier.

Reference Types: FormResponse

bento.V1.Forms.getResponses('test-formid-1234')
  .then(result => console.log(result))
  .catch(error => console.error(error));

Subscribers

`Subscribers.getSubscribers(parameters?: GetSubscribersParameters): Promise<Subscriber<S> | null>`

Returns the subscriber with the specified email or UUID.

Reference Types: GetSubscribersParameters, Subscriber<S>

bento.V1.Subscribers.getSubscribers({
  uuid: '1234',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

bento.V1.Subscribers.getSubscribers({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

`Subscribers.createSubscriber(parameters: CreateSubscriberParameters): Promise<Subscriber<S> | null>`

Creates a subscriber inside of Bento.

Reference Types: CreateSubscriberParameters, Subscriber<S>

bento.V1.Subscribers.createSubscriber({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

Types Reference

`AddFieldParameters<S>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
email	`string`	none	✔️
field	`{ key: keyof S; value: any }`	none	✔️

`AddSubscriberParameters<S>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
date	`Date`	none	❌
email	`string`	none	✔️
fields	`Partial<S>`	none	❌

`AddTagParameters`

Property	Type	Default	Required
email	`string`	none	✔️
tagName	`string`	none	✔️

`BatchImportEventsParameter<S, E>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

The E from above represents the prefix that is used to define your custom events. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
events	[`BentoEvent<S, E>[]`](#BentoEvent<S, E>)	none	✔️

`BatchImportSubscribersParameter<S>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
subscribers	`({ email: string } & Partial<S>)[]`	none	✔️

`BentoEvent<S, E>`

This type is a discriminated union of a few different types. Each of these types are documented below:

`BaseEvent<E>`

The E from above represents the prefix that is used to define your custom events. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
date	`Date`	none	❌
details	`{ [key: string]: any }`	none	✔️
email	`string`	none	✔️
type	`string`	none	✔️

`PurchaseEvent`

Property	Type	Default	Required
date	`Date`	none	❌
details	`PurchaseDetails`	none	✔️
email	`string`	none	✔️
type	`BentoEvents.PURCHASE` \| `'$purchase'`	none	✔️

`SubscribeEvent<S>`

Property	Type	Default	Required
date	`Date`	none	❌
email	`string`	none	✔️
fields	`Partial<S>`	none	❌
type	`BentoEvents.SUBSCRIBE` \| `'$subscribe'`	none	✔️

`TagEvent`

Property	Type	Default	Required
date	`Date`	none	❌
details	`{ tag: string }`	none	✔️
email	`string`	none	✔️
type	`BentoEvents.TAG` \| `'$tag'`	none	✔️

`UnsubscribeEvent`

Property	Type	Default	Required
date	`Date`	none	❌
email	`string`	none	✔️
type	`BentoEvents.UNSUBSCRIBE` \| `'$unsubscribe'`	none	✔️

`UpdateFieldsEvent<S>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
date	`Date`	none	❌
email	`string`	none	✔️
type	`BentoEvents.UPDATE_FIELDS` \| `'$update_fields'`	none	✔️
fields	`Partial<S>`	none	✔️

`BlacklistParameters`

Note that this takes either domain or ip, but never both.

Property	Type	Default	Required
domain	`string`	none	✔️

Property	Type	Default	Required
ip	`string`	none	✔️

`BlacklistResponse`

The results is an object where the key is the name of the blacklist that was checked, and the value is whether or not the domain/IP appeared on that blacklist.

Property	Type	Default	Required
description	`string`	none	✔️
query	`string`	none	✔️
results	`{ [key: string]: boolean }`	none	✔️

`BrowserData`

Property	Type	Default	Required
height	`string`	none	✔️
user_agent	`string`	none	✔️
width	`string`	none	✔️

`ChangeEmailParameters`

Property	Type	Default	Required
oldEmail	`string`	none	✔️
newEmail	`string`	none	✔️

`CreateFieldParameters`

Property	Type	Default	Required
key	`string`	none	✔️

`CreateSubscriberParameters`

Property	Type	Default	Required
email	`string`	none	✔️

`CreateTagParameters`

Property	Type	Default	Required
name	`string`	none	✔️

`EntityType`

This is an enum with the following values:

Name	Value
EVENTS	`'events'`
TAGS	`'tags'`
VISITORS	`'visitors'`
VISITORS_FIELDS	`'visitors-fields'`

`Field`

Property	Type	Default	Required
attributes	`FieldAttributes`	none	✔️
id	`string`	none	✔️
type	`EntityType.VISITORS_FIELDS`	none	✔️

`FieldAttributes`

Property	Type	Default	Required
created_at	`string`	none	✔️
key	`string`	none	✔️
name	`string`	none	✔️
whitelisted	`boolean` \| `null`	none	✔️

`FormResponse`

Property	Type	Default	Required
attributes	`FormResponseAttributes`	none	✔️
id	`string`	none	✔️
type	`EntityType.EVENTS`	none	✔️

`FormResponseAttributes`

Property	Type	Default	Required
data	`FormResponseData`	none	✔️
uuid	`string`	none	✔️

`FormResponseData`

Property	Type	Default	Required
browser	`BrowserData`	none	✔️
date	`string`	none	✔️
details	`{ [key: string]: any }`	none	✔️
fields	`{ [key: string]: any }`	none	✔️
id	`string`	none	✔️
identity	`IdentityData`	none	✔️
ip	`string`	none	✔️
location	`LocationData`	none	✔️
page	`PageData`	none	✔️
site	`string`	none	✔️
type	`string`	none	✔️
visit	`string`	none	✔️
visitor	`string`	none	✔️

`GetSubscribersParameters`

Note that this takes either email or uuid, but never both.

Property	Type	Default	Required
email	`string`	none	✔️

Property	Type	Default	Required
uuid	`string`	none	✔️

`GeolocateParameters`

Property	Type	Default	Required
ip	`string`	none	✔️

`GuessGenderParameters`

Property	Type	Default	Required
name	`string`	none	✔️

`GuessGenderResponse`

Property	Type	Default	Required
confidence	`number` \| `null`	none	✔️
gender	`string` \| `null`	none	✔️

`IdentityData`

Property	Type	Default	Required
email	`string`	none	✔️

`LocationData`

Property	Type	Default	Required
city_name	`string`	none	❌
continent_code	`string`	none	❌
country_code2	`string`	none	❌
country_code3	`string`	none	❌
country_name	`string`	none	❌
ip	`string`	none	❌
latitude	`number`	none	❌
longitude	`number`	none	❌
postal_code	`string`	none	❌
real_region_name	`string`	none	❌
region_name	`string`	none	❌
request	`string`	none	❌

`PageData`

Property	Type	Default	Required
host	`string`	none	✔️
path	`string`	none	✔️
protocol	`string`	none	✔️
referrer	`string`	none	✔️
url	`string`	none	✔️

`PurchaseCart`

Property	Type	Default	Required
abandoned_checkout_url	`string`	none	❌
items	`PurchaseItem[]`	none	❌

`PurchaseDetails`

Property	Type	Default	Required
unique	`{ key: string \| number; }`	none	✔️
value	`{ currency: string; amount: number; }`	none	✔️
cart	`PurchaseCart`	none	❌

`PurchaseItem`

In addition to the properties below, you can pass any other properties that you want as part of the PurchaseItem.

Property	Type	Default	Required
product_sku	`string`	none	❌
product_name	`string`	none	❌
quantity	`number`	none	❌
product_price	`number`	none	❌
product_id	`string`	none	❌

`RemoveFieldParameters<S>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
email	`string`	none	✔️
fieldName	`keyof S`	none	✔️

`RemoveSubscriberParameters`

Property	Type	Default	Required
date	`Date`	none	❌
email	`string`	none	✔️

`RemoveTagParameters`

Property	Type	Default	Required
email	`string`	none	✔️
tagName	`string`	none	✔️

`SubscribeParameters`

Property	Type	Default	Required
email	`string`	none	✔️

`Subscriber<S>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
attributes	`SubscriberAttributes<S>`	none	✔️
id	`string`	none	✔️
type	`EntityType.VISITOR`	none	✔️

`SubscriberAttributes<S>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
cached_tag_ids	`string[]`	none	✔️
email	`string`	none	✔️
fields	`S` \| `null`	none	✔️
unsubscribed_at	`string`	none	✔️
uuid	`string`	none	✔️

`Tag`

Property	Type	Default	Required
created_at	`string`	none	✔️
discarded_at	`string` \| `null`	none	✔️
name	`string` \| `null`	none	✔️
site_id	`string`	none	✔️

`TagAttributes`

Property	Type	Default	Required
attributes	`TagAttributes`	none	✔️
id	`string`	none	✔️
type	`EntityType.TAG`	none	✔️

`TagSubscriberParameters`

Property	Type	Default	Required
date	`Date`	none	❌
email	`string`	none	✔️
tagName	`string`	none	✔️

`TrackParameters<S, E>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

The E from above represents the prefix that is used to define your custom events. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
email	`string`	none	✔️
type	`string`	none	✔️
details	`{ [key: string]: any }`	none	❌
fields	`Partial<S>`	none	❌

`TrackPurchaseParameters`

Property	Type	Default	Required
date	`Date`	none	❌
email	`string`	none	✔️
purchaseDetails	`PurchaseDetails`	none	✔️

`UnsubscribeParameters`

Property	Type	Default	Required
email	`string`	none	✔️

`UpdateFieldsParameters<S>`

The S from above represents the type of your subscriber's custom fields in Bento. This only applies in TypeScript. Please read the TypeScript section for more details.

Property	Type	Default	Required
date	`Date`	none	❌
email	`string`	none	✔️
fields	`Partial<S>`	none	✔️

`ValidateEmailParameters`

Property	Type	Default	Required
email	`string`	none	✔️
ip	`string`	none	❌
name	`string`	none	❌
userAgent	`string`	none	❌

TypeScript

The Bento Node SDK is written entirely in TypeScript and, as such, has first-class support for projects written in TypeScript. It takes advantage of generics to make your code more bullet-proof and reduce bugs throughout your system.

Generics

`S`

The S generic is a type that represents the shape of the custom fields on your Bento subscribers. If this is provided, all of the methods that interact with these fields (including fetching the subscriber from the API) will be typed appropriately.

To set this type, pass it as the first generic parameter when initializing your Analytics object.

type MySubscriberFields = {
  firstName: string;
  lastName: string;
  age: number;
};

const bento = new Analytics<MySubscriberFields>({
  // ... initialization options from above.
});

`E`

The E generic is a string that represents the custom prefix used for your custom commands. This is used to ensure that you are not accidentally changing things on your subscribers that you do not intend to change. It also prevents clashes with using internal Bento events.

To set this type, pass it as the second generic parameter when initializing your Analytics object.

const bento = new Analytics<any, '$myPrefix.'>({
  // ... initialization options from above.
});

Things to know

Tracking: All events must be identified. Anonymous support coming soon!
Tracking: Most events and indexed inside Bento within a few seconds.
If you need support, just let us know!

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/bentonow/bento-node-sdk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The package is available as open source under the terms of the MIT License.

Bento SDK for Node.JS

Installation

Getting Started

Modules

Analytics (Base Module)

tagSubscriber(parameters: TagSubscriberParameters): Promise<boolean>

addSubscriber(parameters: AddSubscriberParameters<S>): Promise<boolean>

removeSubscriber(parameters: RemoveSubscriberParameters): Promise<boolean>

updateFields(parameters: UpdateFieldsParameters<S>): Promise<boolean>

trackPurchase(parameters: TrackPurchaseParameters): Promise<boolean>

track(parameters: TrackParameters<S, E>): Promise<boolean>

Batch

Batch.importSubscribers(parameters: BatchImportSubscribersParameter<S>): Promise<number>

Batch.importEvents(parameters: BatchImportEventsParameter<S, E>): Promise<number>

Batch.sendTransactionalEmails(parameters: BatchsendTransactionalEmailsParameter<S, E>): Promise<number>

Commands

Commands.addTag(parameters: AddTagParameters): Promise<Subscriber<S> | null>

Commands.removeTag(parameters: RemoveTagParameters): Promise<Subscriber<S> | null>

Commands.addField(parameters: AddFieldParameters<S>): Promise<Subscriber<S> | null>

Commands.removeField(parameters: RemoveFieldParameters<S>): Promise<Subscriber<S> | null>

Commands.subscribe(parameters: SubscribeParameters): Promise<Subscriber<S> | null>

Commands.unsubscribe(parameters: UnsubscribeParameters): Promise<Subscriber<S> | null>

Commands.changeEmail(parameters: ChangeEmailParameters): Promise<Subscriber<S> | null>

Experimental

Experimental.validateEmail(parameters: ValidateEmailParameters): Promise<boolean>

Experimental.guessGender(parameters: GuessGenderParameters): Promise<GuessGenderResponse>

Experimental.geolocate(parameters: GeolocateParameters): Promise<LocationData | null>

Experimental.checkBlacklist(parameters: BlacklistParameters): Promise<BlacklistResponse>

Fields

Fields.getFields(): Promise<Field[] | null>

Fields.createField(parameters: CreateFieldParameters): Promise<Field[] | null>

Forms

Forms.getResponses(formIdentifier: string): Promise<FormResponse[] | null>

Subscribers

Subscribers.getSubscribers(parameters?: GetSubscribersParameters): Promise<Subscriber<S> | null>

Subscribers.createSubscriber(parameters: CreateSubscriberParameters): Promise<Subscriber<S> | null>

Tags

Tags.getTags(): Promise<Tag[] | null>

Tags.createTag(parameters: CreateTagParameters): Promise<Tag[] | null>

Types Reference

AddFieldParameters<S>

AddSubscriberParameters<S>

AddTagParameters

BatchImportEventsParameter<S, E>

BatchImportSubscribersParameter<S>

BentoEvent<S, E>

BaseEvent<E>

PurchaseEvent

SubscribeEvent<S>

TagEvent

UnsubscribeEvent

UpdateFieldsEvent<S>

BlacklistParameters

BlacklistResponse

BrowserData

ChangeEmailParameters

CreateFieldParameters

CreateSubscriberParameters

CreateTagParameters

EntityType

Field

FieldAttributes

FormResponse

FormResponseAttributes

FormResponseData

GetSubscribersParameters

GeolocateParameters

GuessGenderParameters

GuessGenderResponse

IdentityData

LocationData

PageData

PurchaseCart

PurchaseDetails

PurchaseItem

RemoveFieldParameters<S>

RemoveSubscriberParameters

RemoveTagParameters

SubscribeParameters

Subscriber<S>

`tagSubscriber(parameters: TagSubscriberParameters): Promise<boolean>`

`addSubscriber(parameters: AddSubscriberParameters<S>): Promise<boolean>`

`removeSubscriber(parameters: RemoveSubscriberParameters): Promise<boolean>`

`updateFields(parameters: UpdateFieldsParameters<S>): Promise<boolean>`

`trackPurchase(parameters: TrackPurchaseParameters): Promise<boolean>`

`track(parameters: TrackParameters<S, E>): Promise<boolean>`

`Batch.importSubscribers(parameters: BatchImportSubscribersParameter<S>): Promise<number>`

`Batch.importEvents(parameters: BatchImportEventsParameter<S, E>): Promise<number>`

`Batch.sendTransactionalEmails(parameters: BatchsendTransactionalEmailsParameter<S, E>): Promise<number>`

`Commands.addTag(parameters: AddTagParameters): Promise<Subscriber<S> | null>`

`Commands.removeTag(parameters: RemoveTagParameters): Promise<Subscriber<S> | null>`

`Commands.addField(parameters: AddFieldParameters<S>): Promise<Subscriber<S> | null>`

`Commands.removeField(parameters: RemoveFieldParameters<S>): Promise<Subscriber<S> | null>`

`Commands.subscribe(parameters: SubscribeParameters): Promise<Subscriber<S> | null>`

`Commands.unsubscribe(parameters: UnsubscribeParameters): Promise<Subscriber<S> | null>`

`Commands.changeEmail(parameters: ChangeEmailParameters): Promise<Subscriber<S> | null>`

`Experimental.validateEmail(parameters: ValidateEmailParameters): Promise<boolean>`

`Experimental.guessGender(parameters: GuessGenderParameters): Promise<GuessGenderResponse>`

`Experimental.geolocate(parameters: GeolocateParameters): Promise<LocationData | null>`

`Experimental.checkBlacklist(parameters: BlacklistParameters): Promise<BlacklistResponse>`

`Fields.getFields(): Promise<Field[] | null>`

`Fields.createField(parameters: CreateFieldParameters): Promise<Field[] | null>`

`Forms.getResponses(formIdentifier: string): Promise<FormResponse[] | null>`

`Subscribers.getSubscribers(parameters?: GetSubscribersParameters): Promise<Subscriber<S> | null>`

`Subscribers.createSubscriber(parameters: CreateSubscriberParameters): Promise<Subscriber<S> | null>`

`Tags.getTags(): Promise<Tag[] | null>`

`Tags.createTag(parameters: CreateTagParameters): Promise<Tag[] | null>`

`AddFieldParameters<S>`

`AddSubscriberParameters<S>`

`AddTagParameters`

`BatchImportEventsParameter<S, E>`

`BatchImportSubscribersParameter<S>`

`BentoEvent<S, E>`

`BaseEvent<E>`

`PurchaseEvent`

`SubscribeEvent<S>`

`TagEvent`

`UnsubscribeEvent`

`UpdateFieldsEvent<S>`

`BlacklistParameters`

`BlacklistResponse`

`BrowserData`

`ChangeEmailParameters`

`CreateFieldParameters`

`CreateSubscriberParameters`

`CreateTagParameters`

`EntityType`

`Field`

`FieldAttributes`

`FormResponse`

`FormResponseAttributes`

`FormResponseData`

`GetSubscribersParameters`

`GeolocateParameters`

`GuessGenderParameters`

`GuessGenderResponse`

`IdentityData`

`LocationData`

`PageData`

`PurchaseCart`

`PurchaseDetails`

`PurchaseItem`

`RemoveFieldParameters<S>`

`RemoveSubscriberParameters`

`RemoveTagParameters`

`SubscribeParameters`

`Subscriber<S>`

`SubscriberAttributes<S>`

`Tag`

`TagAttributes`

`TagSubscriberParameters`

`TrackParameters<S, E>`

`TrackPurchaseParameters`

`UnsubscribeParameters`

`UpdateFieldsParameters<S>`

`ValidateEmailParameters`

`S`

`E`