@hoover-institution/hubspot-lib/types/MarketingEvent.d.ts

A toolkit for deep integration with HubSpot's Marketing Events API with a plugin-based architecture.

import type { AxiosInstance } from "axios";

export type SubscriberStateName = "REGISTERED" | "ATTENDED" | "CANCELED";

export interface HubSpotEvent {
  eventName: string;
  eventType: string;
  startDateTime: string;
  endDateTime: string | null;
  eventOrganizer: string;
  eventDescription: string | null;
  eventUrl: string | null;
  eventCancelled: boolean;
  eventCompleted: boolean;
  customProperties: any[];
  objectId: string;
  id: string;
  createdAt: string;
  updatedAt: string;
  externalEventId: string | number;
  externalAccountId: string;
  status: string;
}

export interface RegisterEmailResult {
  success: boolean;
  email: string;
  subscriberState: number;
  contactId: string;
}

export interface HubSpotContact {
  id: string;
  properties: {
    createdate: string;
    email: string;
    firstname: string;
    hs_object_id: string;
    lastmodifieddate: string;
    lastname: string;
  };
  createdAt: string;
  updatedAt: string;
  archived: boolean;
}

export interface HubSpotContactList {
  listId: string;
  listVersion: number;
  createdAt: string;
  updatedAt: string;
  filtersUpdatedAt: string;
  processingStatus: string;
  createdById: string;
  updatedById: string;
  processingType: string;
  objectTypeId: string;
  name: string;
  listPermissions: {
    teamsWithEditAccess: any[];
    usersWithEditAccess: any[];
  };
  membershipSettings: {
    membershipTeamId: string | null;
    includeUnassigned: boolean | null;
  };
}

export const SUBSCRIBER_STATE: {
  REGISTERED: 2;
  ATTENDED: 1;
  CANCELED: 0;
};

export interface MarketingEventOptions {
  hooks?: number;
  /**
   * Plugins to enable for this instance.
   * Example usage:
   *
   * ```typescript
   * import { PLUGINS } from "./plugins";
   *
   * const options: MarketingEventOptions = {
   *   plugins: [
   *     PLUGINS.MONGO_SYNC,
   *     PLUGINS.LOG_TO_DISCORD,
   *     PLUGINS.LOG_TO_CONSOLE
   *   ]
   * };
   * ```
   */
  plugins?: Array<string | { [event: string]: (...args: any[]) => any }>;
}

export class MarketingEvent {
  constructor(externalAccountId: string, options?: MarketingEventOptions);

  static eventBaseUrl: string;
  static bulkBaseUrl: string;
  static attendanceBaseUrl: string;
  static breakdownBaseUrl: string;

  createEvent(payload: Partial<HubSpotEvent>): Promise<HubSpotEvent>;
  getEvent(externalEventId?: string | number): Promise<HubSpotEvent | null>;
  getEvents(options?: Record<string, any>): Promise<HubSpotEvent[]>;
  deleteEvent(externalEventId?: string | number): Promise<{ success: boolean }>;
  registerEmail(
    email: string,
    externalEventId?: string | number,
    subscriberState?: number,
    fullName?: string
  ): Promise<RegisterEmailResult>;
  getContactsByState(
    externalEventId: string | number,
    subscriberState: number
  ): Promise<HubSpotContact[]>;
  createOrFindContactList(listName: string): Promise<HubSpotContactList>;
  getContactEventState(
    email: string,
    externalEventId: string | number
  ): Promise<SubscriberStateName | null>;
  addContactToList(listId: string, contactId: string): Promise<void>;
  removeContactFromList(listId: string, contactId: string): Promise<void>;
  associateListWithEvent(
    eventId: string | number,
    listId: string
  ): Promise<void>;
  getSubscriberStateName(state: number): SubscriberStateName | "UNKNOWN";

  readonly externalEventId: string | null;
  readonly externalAccountId: string | null;
}