@bentonow/bento-node-sdk 0.2.1 → 1.0.5

package/src/sdk/experimental/index.ts

@@ -1,8 +1,9 @@
 import type { BentoClient } from '../client';
 import type { LocationData } from '../types';
 import type {
+  BlacklistCheckInput,
   BlacklistParameters,
-  BlacklistResponse,
+  BlacklistResponse, BlacklistResult, ContentModerationResult,
   GeolocateParameters,
   GeolocateResponse,
   GuessGenderParameters,
@@ -29,18 +30,13 @@ export class BentoExperimental {
    * @param parameters
    * @returns Promise\<boolean\>
    */
-  public async validateEmail(
-    parameters: ValidateEmailParameters
-  ): Promise<boolean> {
-    const result = await this._client.post<ValidateEmailResponse>(
-      `${this._url}/validation`,
-      {
-        email: parameters.email,
-        ip: parameters.ip,
-        name: parameters.name,
-        user_agent: parameters.userAgent,
-      }
-    );
+  public async validateEmail(parameters: ValidateEmailParameters): Promise<boolean> {
+    const result = await this._client.post<ValidateEmailResponse>(`${this._url}/validation`, {
+      email: parameters.email,
+      ip: parameters.ip,
+      name: parameters.name,
+      user_agent: parameters.userAgent,
+    });
 
     return result.valid;
   }
@@ -58,13 +54,8 @@ export class BentoExperimental {
    * @param parameters
    * @returns Promise\<GuessGenderResponse\>
    */
-  public async guessGender(
-    parameters: GuessGenderParameters
-  ): Promise<GuessGenderResponse> {
-    const result = await this._client.post<GuessGenderResponse>(
-      `${this._url}/gender`,
-      parameters
-    );
+  public async guessGender(parameters: GuessGenderParameters): Promise<GuessGenderResponse> {
+    const result = await this._client.post<GuessGenderResponse>(`${this._url}/gender`, parameters);
 
     return result;
   }
@@ -78,9 +69,7 @@ export class BentoExperimental {
    * @param parameters
    * @returns Promise\<GeolocateResponse\>
    */
-  public async geolocate(
-    parameters: GeolocateParameters
-  ): Promise<LocationData | null> {
+  public async geolocate(parameters: GeolocateParameters): Promise<LocationData | null> {
     const result = await this._client.get<GeolocateResponse>(
       `${this._url}/geolocation`,
       parameters
@@ -100,9 +89,7 @@ export class BentoExperimental {
    * @param parameters
    * @returns Promise\<BlacklistResponse\>
    */
-  public async checkBlacklist(
-    parameters: BlacklistParameters
-  ): Promise<BlacklistResponse> {
+  public async checkBlacklist(parameters: BlacklistParameters): Promise<BlacklistResponse> {
     const result = await this._client.get<BlacklistResponse>(
       `${this._url}/blacklist.json`,
       parameters
@@ -110,4 +97,35 @@ export class BentoExperimental {
 
     return result;
   }
+
+  /**
+   * Checks if a domain or IP is blacklisted
+   * @param input Domain or IP to check
+   * @returns Promise<BlacklistResult>
+   */
+  public async getBlacklistStatus(input: BlacklistCheckInput): Promise<BlacklistResult> {
+    return this._client.get<BlacklistResult>(`${this._url}/blacklist`, input);
+  }
+
+  /**
+   * Performs content moderation on provided text
+   * @param content Text content to moderate
+   * @returns Promise<ContentModerationResult>
+   */
+  public async getContentModeration(content: string): Promise<ContentModerationResult> {
+    return this._client.post<ContentModerationResult>(`${this._url}/moderation`, {
+      content
+    });
+  }
+
+  /**
+   * Gets geolocation data for an IP address
+   * @param ipAddress IP address to geolocate
+   * @returns Promise<LocationData>
+   */
+  public async geoLocateIP(ipAddress: string): Promise<LocationData> {
+    return this._client.get<LocationData>(`${this._url}/geolocation`, {
+      ip: ipAddress
+    });
+  }
 }

package/src/sdk/experimental/types.ts

@@ -28,6 +28,13 @@ export type BlacklistParameters =
       ip: string;
     };
 
+export type BlacklistCheckInput = {
+  domain?: string;
+  ipAddress?: string;
+};
+
+
+
 /**
  * Experimental Method Response Types
  */
@@ -47,3 +54,31 @@ export type BlacklistResponse = {
   query: string;
   results: { [key: string]: boolean };
 };
+
+export type BlacklistResult = {
+  description: string;
+  query: string;
+  results: Record<string, boolean>;
+};
+
+export type ContentModerationResult = {
+  flagged: boolean;
+  categories: {
+    hate: boolean;
+    'hate/threatening': boolean;
+    'self-harm': boolean;
+    sexual: boolean;
+    'sexual/minors': boolean;
+    violence: boolean;
+    'violence/graphic': boolean;
+  };
+  category_scores: {
+    hate: number;
+    'hate/threatening': number;
+    'self-harm': number;
+    sexual: number;
+    'sexual/minors': number;
+    violence: number;
+    'violence/graphic': number;
+  };
+};

package/src/sdk/fields/index.ts

@@ -34,9 +34,7 @@ export class BentoFields {
    * @param parameters \{ key: string \}
    * @returns Promise<Field[]>
    */
-  public async createField(
-    parameters: CreateFieldParameters
-  ): Promise<Field[] | null> {
+  public async createField(parameters: CreateFieldParameters): Promise<Field[] | null> {
     const result = await this._client.post<DataResponse<Field[]>>(this._url, {
       field: parameters,
     });

package/src/sdk/forms/index.ts

@@ -13,15 +13,10 @@ export class BentoForms {
    * @param formIdentifier string
    * @returns Promise\<FormResponse[] | null\>
    */
-  public async getResponses(
-    formIdentifier: string
-  ): Promise<FormResponse[] | null> {
-    const result = await this._client.get<DataResponse<FormResponse[]>>(
-      this._url,
-      {
-        id: formIdentifier,
-      }
-    );
+  public async getResponses(formIdentifier: string): Promise<FormResponse[] | null> {
+    const result = await this._client.get<DataResponse<FormResponse[]>>(this._url, {
+      id: formIdentifier,
+    });
 
     if (Object.keys(result).length === 0 || !result.data) return null;
     return result.data;

package/src/sdk/forms/types.ts

@@ -1,10 +1,4 @@
-import type {
-  BaseEntity,
-  BrowserData,
-  IdentityData,
-  LocationData,
-  PageData,
-} from '../types';
+import type { BaseEntity, BrowserData, IdentityData, LocationData, PageData } from '../types';
 
 /**
  * Core Form Types

package/src/sdk/index.ts

@@ -1,8 +1,11 @@
 export * from './batch';
 export * from './client';
 export * from './commands';
+export * from './email-templates';
 export * from './experimental';
 export * from './fields';
 export * from './forms';
+export * from './sequences';
 export * from './subscribers';
 export * from './tags';
+export * from './workflows';

package/src/sdk/interfaces.ts

@@ -12,4 +12,8 @@ export interface AuthenticationOptions {
 
 export interface ClientOptions {
   baseUrl?: string;
+  /**
+   * Request timeout in milliseconds. Defaults to 30000 (30 seconds).
+   */
+  timeout?: number;
 }

package/src/sdk/sequences/index.ts

@@ -0,0 +1,21 @@
+import type { BentoClient } from '../client';
+import type { DataResponse } from '../client/types';
+import type { Sequence } from './types';
+
+export class BentoSequences {
+  private readonly _url = '/fetch/sequences';
+
+  constructor(private readonly _client: BentoClient) {}
+
+  /**
+   * Returns all of the sequences for the site, including their email templates.
+   *
+   * @returns Promise\<Sequence[]\>
+   */
+  public async getSequences(): Promise<Sequence[]> {
+    const result = await this._client.get<DataResponse<Sequence[]>>(this._url);
+
+    if (!result || Object.keys(result).length === 0) return [];
+    return result.data ?? [];
+  }
+}

package/src/sdk/sequences/types.ts

@@ -0,0 +1,21 @@
+import type { BaseEntity } from '../types';
+
+/**
+ * Embedded Email Template in Sequence
+ */
+export type SequenceEmailTemplate = {
+  id: number;
+  subject: string;
+  stats: Record<string, unknown> | null;
+};
+
+/**
+ * Core Sequence Types
+ */
+export type SequenceAttributes = {
+  name: string;
+  created_at: string;
+  email_templates: SequenceEmailTemplate[];
+};
+
+export type Sequence = BaseEntity<SequenceAttributes>;

package/src/sdk/stats/index.ts

@@ -0,0 +1,37 @@
+import type { BentoClient } from '../client';
+import type { SiteStats, SegmentStats, ReportStats } from './types';
+
+export class BentoStats {
+  private readonly _url = '/stats';
+
+  constructor(private readonly _client: BentoClient) {}
+
+  /**
+   * Retrieves overall statistics for the site
+   * @returns Promise<SiteStats>
+   */
+  public async getSiteStats(): Promise<SiteStats> {
+    const result = await this._client.get<SiteStats>(`${this._url}/site`);
+    return result;
+  }
+
+  /**
+   * Retrieves statistics for a specific segment
+   * @param segmentId ID of the segment to get stats for
+   * @returns Promise<SegmentStats>
+   */
+  public async getSegmentStats(segmentId: string): Promise<SegmentStats> {
+    const result = await this._client.get<SegmentStats>(`${this._url}/segments/${segmentId}`);
+    return result;
+  }
+
+  /**
+   * Retrieves statistics for a specific report
+   * @param reportId ID of the report to get stats for
+   * @returns Promise<ReportStats>
+   */
+  public async getReportStats(reportId: string): Promise<ReportStats> {
+    const result = await this._client.get<ReportStats>(`${this._url}/reports/${reportId}`);
+    return result;
+  }
+}

package/src/sdk/stats/types.ts

@@ -0,0 +1,28 @@
+export type SiteStats = {
+  total_subscribers: number;
+  active_subscribers: number;
+  unsubscribed_count: number;
+  broadcast_count: number;
+  average_open_rate: number;
+  average_click_rate: number;
+};
+
+export type SegmentStats = {
+  segment_id: string;
+  subscriber_count: number;
+  growth_rate: number;
+  engagement_rate: number;
+  last_updated: string;
+};
+
+export type ReportStats = {
+  report_id: string;
+  total_sent: number;
+  total_opens: number;
+  unique_opens: number;
+  total_clicks: number;
+  unique_clicks: number;
+  unsubscribes: number;
+  spam_reports: number;
+  created_at: string;
+};

package/src/sdk/subscribers/index.ts

@@ -1,10 +1,6 @@
 import type { BentoClient } from '../client';
 import type { DataResponse } from '../client/types';
-import type {
-  CreateSubscriberParameters,
-  GetSubscribersParameters,
-  Subscriber,
-} from './types';
+import type { CreateSubscriberParameters, GetSubscribersParameters, Subscriber } from './types';
 
 export class BentoSubscribers<S> {
   private readonly _url = '/fetch/subscribers';
@@ -19,10 +15,7 @@ export class BentoSubscribers<S> {
   public async getSubscribers(
     parameters?: GetSubscribersParameters
   ): Promise<Subscriber<S> | null> {
-    const result = await this._client.get<DataResponse<Subscriber<S>>>(
-      this._url,
-      parameters
-    );
+    const result = await this._client.get<DataResponse<Subscriber<S>>>(this._url, parameters);
 
     if (Object.keys(result).length === 0 || !result.data) return null;
     return result.data;
@@ -37,12 +30,9 @@ export class BentoSubscribers<S> {
   public async createSubscriber(
     parameters: CreateSubscriberParameters
   ): Promise<Subscriber<S> | null> {
-    const result = await this._client.post<DataResponse<Subscriber<S>>>(
-      this._url,
-      {
-        subscriber: parameters,
-      }
-    );
+    const result = await this._client.post<DataResponse<Subscriber<S>>>(this._url, {
+      subscriber: parameters,
+    });
 
     if (Object.keys(result).length === 0 || !result.data) return null;
     return result.data;

package/src/sdk/tags/index.ts

@@ -25,9 +25,7 @@ export class BentoTags {
    * @param parameters CreateTagParameters
    * @returns Promise\<Tag[] | null\>
    */
-  public async createTag(
-    parameters: CreateTagParameters
-  ): Promise<Tag[] | null> {
+  public async createTag(parameters: CreateTagParameters): Promise<Tag[] | null> {
     const result = await this._client.post<DataResponse<Tag[]>>(this._url, {
       tag: parameters,
     });

package/src/sdk/types.ts

@@ -2,7 +2,7 @@
  * Core Types
  */
 
-import type { EntityType } from "./enums";
+import type { EntityType } from './enums';
 
 export type BaseEntity<T> = {
   attributes: T;

package/src/sdk/workflows/index.ts

@@ -0,0 +1,21 @@
+import type { BentoClient } from '../client';
+import type { DataResponse } from '../client/types';
+import type { Workflow } from './types';
+
+export class BentoWorkflows {
+  private readonly _url = '/fetch/workflows';
+
+  constructor(private readonly _client: BentoClient) {}
+
+  /**
+   * Returns all of the workflows for the site, including their email templates.
+   *
+   * @returns Promise\<Workflow[]\>
+   */
+  public async getWorkflows(): Promise<Workflow[]> {
+    const result = await this._client.get<DataResponse<Workflow[]>>(this._url);
+
+    if (!result || Object.keys(result).length === 0) return [];
+    return result.data ?? [];
+  }
+}

package/src/sdk/workflows/types.ts

@@ -0,0 +1,21 @@
+import type { BaseEntity } from '../types';
+
+/**
+ * Embedded Email Template in Workflow
+ */
+export type WorkflowEmailTemplate = {
+  id: number;
+  subject: string;
+  stats: Record<string, unknown> | null;
+};
+
+/**
+ * Core Workflow Types
+ */
+export type WorkflowAttributes = {
+  name: string;
+  created_at: string;
+  email_templates: WorkflowEmailTemplate[];
+};
+
+export type Workflow = BaseEntity<WorkflowAttributes>;

package/src/versions/v1/index.ts

@@ -2,11 +2,14 @@ import {
   BentoBatch,
   BentoClient,
   BentoCommands,
+  BentoEmailTemplates,
   BentoExperimental,
   BentoFields,
   BentoForms,
+  BentoSequences,
   BentoSubscribers,
   BentoTags,
+  BentoWorkflows,
 } from '../../sdk';
 import { BentoEvents } from '../../sdk/batch/enums';
 import type { AnalyticsOptions } from '../../sdk/interfaces';
@@ -18,30 +21,40 @@ import type {
   TrackPurchaseParameters,
   UpdateFieldsParameters,
 } from './types';
+import { BentoBroadcasts } from '../../sdk/broadcasts';
+import { BentoStats } from '../../sdk/stats';
+import type { Subscriber } from '../../sdk/subscribers/types';
 
-export class BentoAPIV1<
-  S = { [key: string]: unknown },
-  E extends string = '$custom'
-> {
+export class BentoAPIV1<S = { [key: string]: unknown }, E extends string = '$custom'> {
   private readonly _client: BentoClient;
 
+  public readonly Broadcasts: BentoBroadcasts;
+  public readonly EmailTemplates: BentoEmailTemplates;
+  public readonly Stats: BentoStats;
   public readonly Batch: BentoBatch<S, E>;
   public readonly Commands: BentoCommands<S>;
   public readonly Experimental: BentoExperimental;
   public readonly Fields: BentoFields;
   public readonly Forms: BentoForms;
+  public readonly Sequences: BentoSequences;
   public readonly Subscribers: BentoSubscribers<S>;
   public readonly Tags: BentoTags;
+  public readonly Workflows: BentoWorkflows;
 
   constructor(options: AnalyticsOptions) {
     this._client = new BentoClient(options);
+    this.Broadcasts = new BentoBroadcasts(this._client);
+    this.EmailTemplates = new BentoEmailTemplates(this._client);
+    this.Stats = new BentoStats(this._client);
     this.Batch = new BentoBatch(this._client);
     this.Commands = new BentoCommands(this._client);
     this.Experimental = new BentoExperimental(this._client);
     this.Fields = new BentoFields(this._client);
     this.Forms = new BentoForms(this._client);
+    this.Sequences = new BentoSequences(this._client);
     this.Subscribers = new BentoSubscribers(this._client);
     this.Tags = new BentoTags(this._client);
+    this.Workflows = new BentoWorkflows(this._client);
   }
 
   /**
@@ -98,9 +111,7 @@ export class BentoAPIV1<
    * @param parameters AddSubscriberParameters
    * @returns Promise\<boolean\>
    */
-  async addSubscriber(
-    parameters: AddSubscriberParameters<S>
-  ): Promise<boolean> {
+  async addSubscriber(parameters: AddSubscriberParameters<S>): Promise<boolean> {
     const result = await this.Batch.importEvents({
       events: [
         {
@@ -134,9 +145,7 @@ export class BentoAPIV1<
    * @param parameters RemoveSubscriberParameters
    * @returns Promise\<boolean\>
    */
-  async removeSubscriber(
-    parameters: RemoveSubscriberParameters
-  ): Promise<boolean> {
+  async removeSubscriber(parameters: RemoveSubscriberParameters): Promise<boolean> {
     const result = await this.Batch.importEvents({
       events: [
         {
@@ -241,4 +250,50 @@ export class BentoAPIV1<
 
     return result === 1;
   }
+
+  /**
+   * 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
+   */
+  public async upsertSubscriber(
+    parameters: Omit<AddSubscriberParameters<S>, 'date'> & {
+      tags?: string;
+      remove_tags?: string;
+    }
+  ): Promise<Subscriber<S> | null> {
+    await this.Batch.importSubscribers({
+      subscribers: [
+        {
+          email: parameters.email,
+          ...parameters.fields,
+          ...(parameters.tags && { tags: parameters.tags }),
+          ...(parameters.remove_tags && { remove_tags: parameters.remove_tags }),
+        } as { email: string } & Partial<S>,
+      ],
+    });
+
+    return this.Subscribers.getSubscribers({
+      email: parameters.email,
+    });
+  }
 }