jonsherrard/bento-node-sdk

🍱 Bento Node SDK and tracking library

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
  • Analytics (Base Module)
    • tagSubscriber(parameters: TagSubscriberParameters): Promise<boolean>
    • addSubscriber(parameters: AddSubscriberParameters): Promise<boolean>
    • removeSubscriber(parameters: RemoveSubscriberParameters): Promise<boolean>
    • updateFields(parameters: UpdateFieldsParameters<S>): Promise<boolean>
    • track(parameters: TrackParameters<S, E>): Promise
    • trackPurchase(parameters: TrackPurchaseParameters): Promise<boolean>
  • Batch
    • .importSubscribers(parameters: BatchImportSubscribersParameter<S>): Promise<number>
    • .importEvents(parameters: BatchImportEventsParameter<S, E>): Promise<number>
    • .sendTransactionalEmails(parameters: BatchsendTransactionalEmailsParameter<S, E>): Promise
  • Commands
    • .addTag(parameters: AddTagParameters): Promise<Subscriber<S> | null>
    • .removeTag(parameters: RemoveTagParameters): Promise<Subscriber<S> | null>
    • .addField(parameters: AddFieldParameters<S>): Promise<Subscriber<S> | null>
    • .removeField(parameters: RemoveFieldParameters<S>): Promise<Subscriber<S> | null>
    • .subscribe(parameters: SubscribeParameters): Promise<Subscriber<S> | null>
    • .unsubscribe(parameters: UnsubscribeParameters): Promise<Subscriber<S> | null>
  • Experimental
    • .validateEmail(parameters: ValidateEmailParameters): Promise<boolean>
    • .guessGender(parameters: GuessGenderParameters): Promise<GuessGenderResponse>
    • .geolocate(parameters: GeolocateParameters): Promise<LocationData | null>
    • .checkBlacklist(parameters: BlacklistParameters): Promise<BlacklistResponse>
  • Fields
    • .getFields(): Promise<Field[] | null>
    • .createField(parameters: CreateFieldParameters): Promise<Field[] | null>
  • Forms
    • .getResponses(formIdentifier: string): Promise<FormResponse[] | null>
  • Subscribers
    • .getSubscribers(parameters?: GetSubscribersParameters): Promise<Subscriber<S> | null>
    • .createSubscriber(parameters: CreateSubscriberParameters): Promise<Subscriber<S> | null>
  • Tags
    • .getTags(): Promise<Tag[] | null>
    • .createTag(parameters: CreateTagParameters): Promise<Tag[] | null>
• 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));

Tags

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

Returns all of the fields for the site.

Reference Types: Tag

bento.V1.Tags.getTags()
  .then(result => console.log(result))
  .catch(error => console.error(error));

---

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

Creates a tag inside of Bento.

Reference Types: Tag

bento.V1.Tags.createTag({
  name: 'test tag',
})
  .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

1. Tracking: All events must be identified. Anonymous support coming soon!
2. Tracking: Most events and indexed inside Bento within a few seconds.
3. 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.