@bentonow/bento-node-sdk v0.2.0

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.

• 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>
    • trackPurchase(parameters: TrackPurchaseParameters): Promise\<boolean>
  • Batch
    • .importSubscribers(parameters: BatchImportSubscribersParameter\<S>): Promise\<number>
    • .importEvents(parameters: BatchImportEventsParameter\<S, E>): Promise\<number>
  • 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

Get Started

To get started with tracking things in Bento, simply initialize the client and run wild!

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.addSubscriber({
  email: 'test@bentonow.com',
})
  .then(result => console.log(result))
  .catch(error => console.error(error));

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

bento.V1.trackPurchase({
  email: 'test@bentonow.com',
  purchaseDetails: {
    unique: { key: 1234 },
    value: { amount: 100, currency: 'USD' },
  },
  cart: {
    abandoned_checkout_url: '',
  },
});

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:

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.

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.

AddTagParameters

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.

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.

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.

PurchaseEvent

SubscribeEvent<S>

TagEvent

UnsubscribeEvent

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.

BlacklistParameters

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

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.

BrowserData

ChangeEmailParameters

CreateFieldParameters

CreateSubscriberParameters

CreateTagParameters

EntityType

This is an enum with the following values:

Field

FieldAttributes

FormResponse

FormResponseAttributes

FormResponseData

GetSubscribersParameters

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

GeolocateParameters

GuessGenderParameters

GuessGenderResponse

IdentityData

LocationData

PageData

PurchaseCart

PurchaseDetails

PurchaseItem

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

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.

RemoveSubscriberParameters

RemoveTagParameters

SubscribeParameters

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.

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.

Tag

TagAttributes

TagSubscriberParameters

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.

TrackPurchaseParameters

UnsubscribeParameters

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.

ValidateEmailParameters

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.