@bentonow/bento-node-sdk 0.2.1 → 1.0.5

package/dist/versions/v1/index.d.ts

@@ -1,132 +1,168 @@
-import { BentoBatch, BentoCommands, BentoExperimental, BentoFields, BentoForms, BentoSubscribers, BentoTags } from '../../sdk';
-import type { AnalyticsOptions } from '../../sdk/interfaces';
-import type { AddSubscriberParameters, RemoveSubscriberParameters, TagSubscriberParameters, TrackParameters, TrackPurchaseParameters, UpdateFieldsParameters } from './types';
-export declare class BentoAPIV1<S = {
-    [key: string]: unknown;
-}, E extends string = '$custom'> {
-    private readonly _client;
-    readonly Batch: BentoBatch<S, E>;
-    readonly Commands: BentoCommands<S>;
-    readonly Experimental: BentoExperimental;
-    readonly Fields: BentoFields;
-    readonly Forms: BentoForms;
-    readonly Subscribers: BentoSubscribers<S>;
-    readonly Tags: BentoTags;
-    constructor(options: AnalyticsOptions);
-    /**
-     * **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.
-     *
-     * @param parameters TagSubscriberParameters
-     * @returns Promise\<boolean\>
-     */
-    tagSubscriber(parameters: TagSubscriberParameters): 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
-     * as well as a `Date` which will backdate the event. If no date is supplied, then the event will
-     * default to the current time.
-     *
-     * 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.
-     *
-     * @param parameters AddSubscriberParameters
-     * @returns Promise\<boolean\>
-     */
-    addSubscriber(parameters: AddSubscriberParameters<S>): 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.
-     *
-     * You may optionally pass a `Date` which will backdate the event. If no date is supplied, then the event
-     * will default to the current time.
-     *
-     * 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.
-     *
-     * @param parameters RemoveSubscriberParameters
-     * @returns Promise\<boolean\>
-     */
-    removeSubscriber(parameters: RemoveSubscriberParameters): 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.
-     *
-     * You may optionally pass a `Date` which will backdate the event. If no date is supplied, then the event
-     * will default to the current time.
-     *
-     * 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.
-     *
-     * @param parameters UpdateFieldsParameters\<S\>
-     * @returns Promise\<boolean\>
-     */
-    updateFields(parameters: UpdateFieldsParameters<S>): 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`.
-     *
-     * You may optionally pass a `Date` which will backdate the event. If no date is supplied, then the event
-     * will default to the current time.
-     *
-     * 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.
-     *
-     * @param parameters TrackPurchaseParameters
-     * @returns Promise\<boolean\>
-     */
-    trackPurchase(parameters: TrackPurchaseParameters): Promise<boolean>;
-    /**
-     * **This TRIGGERS automations!** - There is no way to achieve this same behavior without triggering
-     * automations.
-     *
-     * Tracks a custom event in Bento.
-     *
-     * You may optionally pass a `Date` which will backdate the event. If no date is supplied, then the event
-     * will default to the current time.
-     *
-     * 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.
-     *
-     * @param parameters TrackParameters<S, E>
-     * @returns Promise\<boolean\>
-     */
-    track(parameters: TrackParameters<S, E>): Promise<boolean>;
-}
+import { BentoBatch, BentoCommands, BentoEmailTemplates, BentoExperimental, BentoFields, BentoForms, BentoSequences, BentoSubscribers, BentoTags, BentoWorkflows } from '../../sdk';
+import type { AnalyticsOptions } from '../../sdk/interfaces';
+import type { AddSubscriberParameters, RemoveSubscriberParameters, TagSubscriberParameters, TrackParameters, TrackPurchaseParameters, UpdateFieldsParameters } from './types';
+import { BentoBroadcasts } from '../../sdk/broadcasts';
+import { BentoStats } from '../../sdk/stats';
+import type { Subscriber } from '../../sdk/subscribers/types';
+export declare class BentoAPIV1<S = {
+    [key: string]: unknown;
+}, E extends string = '$custom'> {
+    private readonly _client;
+    readonly Broadcasts: BentoBroadcasts;
+    readonly EmailTemplates: BentoEmailTemplates;
+    readonly Stats: BentoStats;
+    readonly Batch: BentoBatch<S, E>;
+    readonly Commands: BentoCommands<S>;
+    readonly Experimental: BentoExperimental;
+    readonly Fields: BentoFields;
+    readonly Forms: BentoForms;
+    readonly Sequences: BentoSequences;
+    readonly Subscribers: BentoSubscribers<S>;
+    readonly Tags: BentoTags;
+    readonly Workflows: BentoWorkflows;
+    constructor(options: AnalyticsOptions);
+    /**
+     * **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.
+     *
+     * @param parameters TagSubscriberParameters
+     * @returns Promise\<boolean\>
+     */
+    tagSubscriber(parameters: TagSubscriberParameters): 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
+     * as well as a `Date` which will backdate the event. If no date is supplied, then the event will
+     * default to the current time.
+     *
+     * 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.
+     *
+     * @param parameters AddSubscriberParameters
+     * @returns Promise\<boolean\>
+     */
+    addSubscriber(parameters: AddSubscriberParameters<S>): 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.
+     *
+     * You may optionally pass a `Date` which will backdate the event. If no date is supplied, then the event
+     * will default to the current time.
+     *
+     * 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.
+     *
+     * @param parameters RemoveSubscriberParameters
+     * @returns Promise\<boolean\>
+     */
+    removeSubscriber(parameters: RemoveSubscriberParameters): 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.
+     *
+     * You may optionally pass a `Date` which will backdate the event. If no date is supplied, then the event
+     * will default to the current time.
+     *
+     * 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.
+     *
+     * @param parameters UpdateFieldsParameters\<S\>
+     * @returns Promise\<boolean\>
+     */
+    updateFields(parameters: UpdateFieldsParameters<S>): 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`.
+     *
+     * You may optionally pass a `Date` which will backdate the event. If no date is supplied, then the event
+     * will default to the current time.
+     *
+     * 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.
+     *
+     * @param parameters TrackPurchaseParameters
+     * @returns Promise\<boolean\>
+     */
+    trackPurchase(parameters: TrackPurchaseParameters): Promise<boolean>;
+    /**
+     * **This TRIGGERS automations!** - There is no way to achieve this same behavior without triggering
+     * automations.
+     *
+     * Tracks a custom event in Bento.
+     *
+     * You may optionally pass a `Date` which will backdate the event. If no date is supplied, then the event
+     * will default to the current time.
+     *
+     * 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.
+     *
+     * @param parameters TrackParameters<S, E>
+     * @returns Promise\<boolean\>
+     */
+    track(parameters: TrackParameters<S, E>): Promise<boolean>;
+    /**
+     * Upserts a subscriber in Bento. If the subscriber exists, their data will be updated.
+     * If they don't exist, they will be created with the provided data.
+     *
+     * This method still relies on the batch import queue (which can take 1-5 minutes to
+     * finish processing), but it automatically attempts to fetch and return the subscriber
+     * record after the import has been queued.
+     *
+     * @example
+     * ```typescript
+     * const subscriber = await analytics.V1.upsertSubscriber({
+     *   email: 'user@example.com',
+     *   fields: {
+     *     firstName: 'John',
+     *     lastName: 'Doe'
+     *   },
+     *   tags: 'lead,mql',
+     *   remove_tags: 'customer'
+     * });
+     * ```
+     *
+     * @param parameters Object containing subscriber data including email, fields, and tags
+     * @returns Promise<Subscriber<S> | null> The created or updated subscriber
+     */
+    upsertSubscriber(parameters: Omit<AddSubscriberParameters<S>, 'date'> & {
+        tags?: string;
+        remove_tags?: string;
+    }): Promise<Subscriber<S> | null>;
+}

package/dist/versions/v1/types.d.ts

@@ -1,31 +1,31 @@
-import type { BaseEvent, PurchaseDetails } from '../../sdk/batch/events';
-/**
- * API Method Parameter Types
- */
-export type TagSubscriberParameters = {
-    date?: Date;
-    email: string;
-    tagName: string;
-};
-export type AddSubscriberParameters<S> = {
-    date?: Date;
-    email: string;
-    fields?: Partial<S>;
-};
-export type RemoveSubscriberParameters = {
-    date?: Date;
-    email: string;
-};
-export type TrackPurchaseParameters = {
-    date?: Date;
-    email: string;
-    purchaseDetails: PurchaseDetails;
-};
-export type UpdateFieldsParameters<S> = {
-    date?: Date;
-    email: string;
-    fields: Partial<S>;
-};
-export type TrackParameters<S, E extends string> = BaseEvent<E> & {
-    fields: Partial<S>;
-};
+import type { BaseEvent, PurchaseDetails } from '../../sdk/batch/events';
+/**
+ * API Method Parameter Types
+ */
+export type TagSubscriberParameters = {
+    date?: Date;
+    email: string;
+    tagName: string;
+};
+export type AddSubscriberParameters<S> = {
+    date?: Date;
+    email: string;
+    fields?: Partial<S>;
+};
+export type RemoveSubscriberParameters = {
+    date?: Date;
+    email: string;
+};
+export type TrackPurchaseParameters = {
+    date?: Date;
+    email: string;
+    purchaseDetails: PurchaseDetails;
+};
+export type UpdateFieldsParameters<S> = {
+    date?: Date;
+    email: string;
+    fields: Partial<S>;
+};
+export type TrackParameters<S, E extends string> = BaseEvent<E> & {
+    fields: Partial<S>;
+};

package/package.json

@@ -1,34 +1,29 @@
 {
-  "version": "0.2.1",
+  "name": "@bentonow/bento-node-sdk",
+  "version": "1.0.5",
+  "description": "🍱 Bento Node.JS SDK and tracking library",
+  "author": "Backpack Internet",
   "license": "MIT",
   "main": "dist/index.js",
-  "typings": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist",
     "src"
   ],
   "engines": {
-    "node": ">=12"
+    "node": ">=18"
   },
   "scripts": {
-    "start": "tsdx watch",
-    "build": "tsdx build",
-    "test": "tsdx test",
-    "lint": "tsdx lint",
-    "prepare": "tsdx build",
+    "build": "bun build ./src/index.ts --outdir dist && tsc --emitDeclarationOnly",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepublishOnly": "bun run build",
     "size": "size-limit",
     "analyze": "size-limit --why"
   },
-  "peerDependencies": {},
-  "husky": {
-    "hooks": {
-      "pre-commit": "tsdx lint"
-    }
-  },
-  "name": "@bentonow/bento-node-sdk",
-  "author": "Backpack Internet",
-  "module": "dist/bento-node-sdk.esm.js",
-  "description": "🍱 Bento Node.JS SDK and tracking library",
   "repository": {
     "type": "git",
     "url": "git://github.com/bentonow/bento-node-sdk.git"
@@ -37,32 +32,24 @@
     "url": "https://github.com/bentonow/bento-node-sdk/issues"
   },
   "homepage": "https://bentonow.com",
-  "size-limit": [
-    {
-      "path": "dist/bento-node-sdk.cjs.production.min.js",
-      "limit": "10 KB"
-    },
-    {
-      "path": "dist/bento-node-sdk.esm.js",
-      "limit": "10 KB"
-    }
-  ],
   "devDependencies": {
-    "@size-limit/preset-small-lib": "^5.0.3",
-    "@types/isomorphic-fetch": "^0.0.35",
-    "@types/jest": "^27.0.1",
-    "@typescript-eslint/eslint-plugin": "^5.30.7",
-    "@typescript-eslint/parser": "^5.30.7",
-    "@weiran.zsd/tsdx": "^0.15.2",
-    "eslint": "^7.32.0",
-    "husky": "^7.0.1",
-    "msw": "^0.34.0",
-    "prettier": "^2.7.1",
-    "size-limit": "^5.0.3",
-    "tslib": "^2.3.1",
-    "typescript": "^4.3.5"
+    "@size-limit/preset-small-lib": "^11.1.5",
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.19.1",
+    "@typescript-eslint/parser": "^8.24.0",
+    "bun-types": "latest",
+    "eslint": "^9.20.1",
+    "prettier": "^3.4.2",
+    "size-limit": "^11.1.6",
+    "typescript": "^5.7.2"
   },
   "dependencies": {
-    "cross-fetch": "^4.0.0"
-  }
-}
+    "cross-fetch": "^4.1.0"
+  },
+  "size-limit": [
+    {
+      "path": "dist/index.js",
+      "limit": "15 KB"
+    }
+  ]
+}

package/src/sdk/batch/events.ts

@@ -6,7 +6,7 @@ export type PurchaseItem = {
   quantity?: number;
   product_price?: number;
   product_id?: string;
-} & { [key: string]: string };
+} & { [key: string]: string | number };
 
 export type PurchaseCart = {
   abandoned_checkout_url?: string;

package/src/sdk/batch/index.ts

@@ -41,26 +41,21 @@ export class BentoBatch<S, E extends string> {
    * @param parameters
    * @returns Promise\<number\>
    */
-  public async importSubscribers(
-    parameters: BatchImportSubscribersParameter<S>
-  ): Promise<number> {
+  public async importSubscribers(parameters: BatchImportSubscribersParameter<S>): Promise<number> {
     if (parameters.subscribers.length === 0) {
-      throw new TooFewSubscribersError(
-        `You must send between 1 and 1,000 subscribers.`
-      );
+      throw new TooFewSubscribersError(`You must send between 1 and 1,000 subscribers.`);
     }
 
     if (parameters.subscribers.length > this._maxBatchSize) {
-      throw new TooManySubscribersError(
-        `You must send between 1 and 1,000 subscribers.`
-      );
+      throw new TooManySubscribersError(`You must send between 1 and 1,000 subscribers.`);
     }
 
     const result = await this._client.post<BatchImportSubscribersResponse>(
       `${this._url}/subscribers`,
       {
         subscribers: parameters.subscribers,
-      }
+      },
+      { timeout: null }
     );
 
     return result.results;
@@ -77,9 +72,7 @@ export class BentoBatch<S, E extends string> {
    * @param parameters
    * @returns Promise\<number\>
    */
-  public async importEvents(
-    parameters: BatchImportEventsParameter<S, E>
-  ): Promise<number> {
+  public async importEvents(parameters: BatchImportEventsParameter<S, E>): Promise<number> {
     if (parameters.events.length === 0) {
       throw new TooFewEventsError(`You must send between 1 and 1,000 events.`);
     }
@@ -92,7 +85,8 @@ export class BentoBatch<S, E extends string> {
       `${this._url}/events`,
       {
         events: parameters.events,
-      }
+      },
+      { timeout: null }
     );
 
     return result.results;
@@ -105,7 +99,7 @@ export class BentoBatch<S, E extends string> {
    * 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 tsags that will be injected into the email.
+   * liquid tags that will be injected into the email.
    *
    * Returns the number of events that were imported.
    *
@@ -123,13 +117,12 @@ export class BentoBatch<S, E extends string> {
       throw new TooManyEmailsError(`You must send between 1 and 100 emails.`);
     }
 
-    const result =
-      await this._client.post<BatchsendTransactionalEmailsResponse>(
-        `${this._url}/emails`,
-        {
-          emails: parameters.emails,
-        }
-      );
+    const result = await this._client.post<BatchsendTransactionalEmailsResponse>(
+      `${this._url}/emails`,
+      {
+        emails: parameters.emails,
+      }
+    );
 
     return result.results;
   }

package/src/sdk/broadcasts/index.ts

@@ -0,0 +1,44 @@
+import type { BentoClient } from '../client';
+import type { DataResponse } from '../client/types';
+import type { Broadcast, CreateBroadcastInput, EmailData } from './types';
+
+export class BentoBroadcasts {
+  private readonly _fetchUrl = '/fetch/broadcasts';
+  private readonly _batchUrl = '/batch/broadcasts';
+  private readonly _emailsUrl = '/batch/emails';
+
+  constructor(private readonly _client: BentoClient) {}
+
+  /**
+   * Creates transactional emails in batch
+   * @param emails Array of email data to send
+   * @returns Promise<number> Number of emails successfully created
+   */
+  public async createEmails(emails: EmailData[]): Promise<number> {
+    const result = await this._client.post<{ results: number }>(this._emailsUrl, {
+      emails,
+    });
+    return result.results;
+  }
+
+  /**
+   * Retrieves all broadcasts for the site
+   * @returns Promise<Broadcast[]>
+   */
+  public async getBroadcasts(): Promise<Broadcast[]> {
+    const result = await this._client.get<DataResponse<Broadcast[]>>(this._fetchUrl);
+    return result.data ?? [];
+  }
+
+  /**
+   * Creates new broadcast campaigns
+   * @param broadcasts Array of broadcast data to create
+   * @returns Promise<Broadcast[]>
+   */
+  public async createBroadcast(broadcasts: CreateBroadcastInput[]): Promise<Broadcast[]> {
+    const result = await this._client.post<DataResponse<Broadcast[]>>(this._batchUrl, {
+      broadcasts,
+    });
+    return result.data ?? [];
+  }
+}

package/src/sdk/broadcasts/types.ts

@@ -0,0 +1,38 @@
+import type { BaseEntity } from '../types';
+
+export type BroadcastType = 'plain' | 'html' | 'markdown';
+
+export type ContactData = {
+  name: string;
+  email: string;
+};
+
+export type BroadcastAttributes = {
+  name: string;
+  subject: string;
+  content: string;
+  type: BroadcastType;
+  from: ContactData;
+  inclusive_tags?: string;
+  exclusive_tags?: string;
+  segment_id?: string;
+  batch_size_per_hour: number;
+  created_at: string;
+};
+
+export type Broadcast = BaseEntity<BroadcastAttributes>;
+
+export type CreateBroadcastInput = Omit<BroadcastAttributes, 'created_at'>;
+
+/**
+ * Email data for transactional emails.
+ * Note: This is the same structure as TransactionalEmail in batch/types.ts
+ */
+export type EmailData = {
+  to: string;
+  from: string;
+  subject: string;
+  html_body: string;
+  transactional: boolean;
+  personalizations?: Record<string, string | number | boolean>;
+};