@segment/analytics-browser-actions-hubspot 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@segment/analytics-browser-actions-hubspot",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "./dist/cjs",
+  "module": "./dist/esm",
+  "scripts": {
+    "build": "yarn build:esm && yarn build:cjs",
+    "build:cjs": "tsc --module commonjs --outDir ./dist/cjs",
+    "build:esm": "tsc --outDir ./dist/esm"
+  },
+  "typings": "./dist/esm",
+  "dependencies": {
+    "@segment/actions-core": "^3.71.0",
+    "@segment/browser-destination-runtime": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": "*"
+  }
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,70 @@
+import { Subscription } from '@segment/browser-destination-runtime/types'
+import { Analytics, Context } from '@segment/analytics-next'
+import hubspotDestination, { destination } from '../index'
+import nock from 'nock'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackCustomBehavioralEvent',
+    name: 'Track Custom Behavioral Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      event_name: {
+        '@path': '$.event'
+      }
+    }
+  }
+]
+
+describe('Hubspot Web (Actions)', () => {
+  beforeEach(() => {
+    nock('https://js.hs-scripts.com/').get('/12345.js').reply(200, "window._hsq = '🇺🇸'")
+    nock('https://js-eu1.hs-scripts.com/').get('/12345.js').reply(200, "window._hsq = '🇪🇺'")
+    nock('https://https://js.hsforms.net').get('forms/v2.js').reply(200, "window.hbspt = {forms: '1232'}")
+  })
+  test('loads hubspot analytics with just a HubID', async () => {
+    const [event] = await hubspotDestination({
+      portalId: '12345',
+      subscriptions
+    })
+
+    jest.spyOn(destination, 'initialize')
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+    expect(window._hsq).toEqual('🇺🇸')
+    expect(window.hbspt).toBeUndefined()
+  })
+
+  test('loads hubspot analytics with EU script', async () => {
+    const [event] = await hubspotDestination({
+      portalId: '12345',
+      enableEuropeanDataCenter: true,
+      subscriptions
+    })
+
+    jest.spyOn(destination, 'initialize')
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+
+    expect(window._hsq).toEqual('🇪🇺')
+    expect(window.hbspt).toBeUndefined()
+  })
+
+  test('loads hubspot forms SDK', async () => {
+    const [event] = await hubspotDestination({
+      portalId: '12345',
+      loadFormsSDK: true,
+      subscriptions
+    })
+    jest.spyOn(destination, 'initialize')
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+
+    expect(window._hsq).toEqual('🇺🇸')
+    expect(window.hbspt).toBeDefined()
+  })
+})

package/src/generated-types.ts

@@ -0,0 +1,24 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * The Hub ID of your HubSpot account.
+   */
+  portalId: string
+  /**
+   * Enable this option if you would like Segment to load the HubSpot SDK for EU data residency.
+   */
+  enableEuropeanDataCenter?: boolean
+  /**
+   * Enable this option to fire a `trackPageView` HubSpot event immediately after each Segment `identify` call to flush the data to HubSpot immediately.
+   */
+  flushIdentifyImmediately?: boolean
+  /**
+   * Format the event names for custom behavioral event automatically to standard HubSpot format (`pe<HubID>_event_name`).
+   */
+  formatCustomBehavioralEventNames?: boolean
+  /**
+   * Enable this option if you would like Segment to automatically load the HubSpot Forms SDK onto your site.
+   */
+  loadFormsSDK?: boolean
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+import type { Settings } from './generated-types'
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+
+import trackCustomBehavioralEvent from './trackCustomBehavioralEvent'
+
+import trackPageView from './trackPageView'
+
+import upsertContact from './upsertContact'
+import type { Hubspot } from './types'
+import { defaultValues } from '@segment/actions-core'
+
+declare global {
+  interface Window {
+    _hsq: any
+    hbspt: any
+  }
+}
+
+// Switch from unknown to the partner SDK client types
+export const destination: BrowserDestinationDefinition<Settings, Hubspot> = {
+  name: 'Hubspot Web (Actions)',
+  slug: 'actions-hubspot-web',
+  mode: 'device',
+  presets: [
+    {
+      name: 'Track Custom Behavioral Event',
+      subscribe: 'type = "track"',
+      partnerAction: 'trackCustomBehavioralEvent',
+      mapping: defaultValues(trackCustomBehavioralEvent.fields)
+    },
+    {
+      name: 'Upsert Contact',
+      subscribe: 'type = "identify"',
+      partnerAction: 'upsertContact',
+      mapping: defaultValues(upsertContact.fields)
+    },
+    {
+      name: 'Track Page View',
+      subscribe: 'type = "page"',
+      partnerAction: 'trackPageView',
+      mapping: defaultValues(trackPageView.fields)
+    }
+  ],
+  settings: {
+    portalId: {
+      description: 'The Hub ID of your HubSpot account.',
+      label: 'Hub ID',
+      type: 'string',
+      required: true
+    },
+    enableEuropeanDataCenter: {
+      description: 'Enable this option if you would like Segment to load the HubSpot SDK for EU data residency.',
+      label: 'Enable the European Data Center SDK.',
+      type: 'boolean',
+      required: false
+    },
+    flushIdentifyImmediately: {
+      description: 'Enable this option to fire a `trackPageView` HubSpot event immediately after each Segment `identify` call to flush the data to HubSpot immediately.',
+      label: 'Flush Identify Calls Immediately',
+      type: 'boolean',
+      required: false
+    },
+    formatCustomBehavioralEventNames: {
+      description: 'Format the event names for custom behavioral event automatically to standard HubSpot format (`pe<HubID>_event_name`).',
+      label: 'Format Custom Behavioral Event Names',
+      type: 'boolean',
+      required: false,
+      default: true
+    },
+    loadFormsSDK: {
+      description: 'Enable this option if you would like Segment to automatically load the HubSpot Forms SDK onto your site.',
+      label: 'Load Forms SDK',
+      type: 'boolean',
+      required: false,
+      default: false
+    }
+  },
+
+  initialize: async ({ settings }, deps) => {
+    const scriptPath = settings.enableEuropeanDataCenter
+      ? `https://js-eu1.hs-scripts.com/${settings.portalId}.js`
+      : `https://js.hs-scripts.com/${settings.portalId}.js`
+
+    const formsScriptPath = settings.enableEuropeanDataCenter
+      ? 'https://js-eu1.hsforms.net/forms/v2.js'
+      : 'https://js.hsforms.net/forms/v2.js'
+
+    await deps.loadScript(scriptPath)
+    if (settings.loadFormsSDK) {
+      await deps.loadScript(formsScriptPath)
+    }
+    await deps.resolveWhen(
+      () =>
+        !!(window._hsq && window._hsq.push !== Array.prototype.push) &&
+        (!settings.loadFormsSDK || !!(window.hbspt && window.hbspt.forms)),
+      100
+    )
+    return window._hsq
+  },
+
+  actions: {
+    trackCustomBehavioralEvent,
+    trackPageView,
+    upsertContact
+  }
+}
+
+export default browserDestination(destination)

package/src/trackCustomBehavioralEvent/__tests__/index.test.ts

@@ -0,0 +1,124 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import hubspotDestination, { destination } from '../../index'
+import { Hubspot } from '../../types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackCustomBehavioralEvent',
+    name: 'Track Custom Behavioral Event',
+    enabled: true,
+    subscribe: 'type = "track"',
+    mapping: {
+      name: {
+        '@path': '$.event'
+      },
+      properties: {
+        '@path': '$.properties'
+      }
+    }
+  }
+]
+
+describe('Hubspot.trackCustomBehavioralEvent', () => {
+  const settings = {
+    portalId: '1234',
+    formatCustomBehavioralEventNames: true
+  }
+
+  let mockHubspot: Hubspot
+  let trackCustomBehavioralEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [trackCustomBehavioralEventPlugin] = await hubspotDestination({
+      ...settings,
+      subscriptions
+    })
+    trackCustomBehavioralEvent = trackCustomBehavioralEventPlugin
+
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockHubspot = {
+        push: jest.fn()
+      }
+      return Promise.resolve(mockHubspot)
+    })
+    await trackCustomBehavioralEvent.load(Context.system(), {} as Analytics)
+  })
+
+  test('maps custom traits correctly', async () => {
+    const context = new Context({
+      type: 'track',
+      event: 'purchased a 🍱',
+      properties: {
+        type: '🍣',
+        price: '$12.00',
+        currency: 'USD'
+      }
+    })
+    await trackCustomBehavioralEvent.track?.(context)
+
+    expect(mockHubspot.push).toHaveBeenCalledWith([
+      'trackCustomBehavioralEvent',
+      { name: 'pe1234_purchased_a_🍱', properties: { currency: 'USD', price: '$12.00', type: '🍣' } }
+    ])
+  })
+
+  test('flattens nested object properties', async () => {
+    const context = new Context({
+      type: 'track',
+      event: 'purchased a 🍱',
+      properties: {
+        type: '🍣',
+        price: '$12.00',
+        currency: 'USD',
+        sides: {
+          item1: '🧉',
+          item2: '🧋',
+          'auxilery Sauces': {
+            'Soy Sauce': '🍶'
+          }
+        }
+      }
+    })
+    await trackCustomBehavioralEvent.track?.(context)
+
+    expect(mockHubspot.push).toHaveBeenCalledWith([
+      'trackCustomBehavioralEvent',
+      {
+        name: 'pe1234_purchased_a_🍱',
+        properties: {
+          currency: 'USD',
+          price: '$12.00',
+          type: '🍣',
+          sides_item1: '🧉',
+          sides_item2: '🧋',
+          sides_auxilery_sauces_soy_sauce: '🍶'
+        }
+      }
+    ])
+  })
+
+  test('snake case spaces and dots', async () => {
+    const context = new Context({
+      type: 'track',
+      event: 'purchased a 🍱',
+      properties: {
+        type: '🍣',
+        price: '$12.00',
+        currency: 'USD',
+        'type of fish': '🐟',
+        'brown.rice': false
+      }
+    })
+    await trackCustomBehavioralEvent.track?.(context)
+
+    expect(mockHubspot.push).toHaveBeenCalledWith([
+      'trackCustomBehavioralEvent',
+      {
+        name: 'pe1234_purchased_a_🍱',
+        properties: { currency: 'USD', price: '$12.00', type: '🍣', type_of_fish: '🐟', brown_rice: false }
+      }
+    ])
+  })
+})

package/src/trackCustomBehavioralEvent/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The internal event name assigned by HubSpot. This can be found in your HubSpot account. If the "Format Custom Behavioral Event Names" setting is enabled, Segment will automatically convert your Segment event name into the expected HubSpot internal event name format.
+   */
+  name: string
+  /**
+   * A list of key-value pairs that describe the event.
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/trackCustomBehavioralEvent/index.ts

@@ -0,0 +1,48 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { Hubspot } from '../types'
+import { flatten } from '../utils/flatten'
+
+// Change from unknown to the partner SDK types
+const action: BrowserActionDefinition<Settings, Hubspot, Payload> = {
+  title: 'Track Custom Behavioral Event',
+  description: 'Send a custom behavioral event to HubSpot.',
+  platform: 'web',
+  defaultSubscription: 'type = "track"',
+  fields: {
+    name: {
+      description: 'The internal event name assigned by HubSpot. This can be found in your HubSpot account. If the "Format Custom Behavioral Event Names" setting is enabled, Segment will automatically convert your Segment event name into the expected HubSpot internal event name format.',
+      label: 'Event Name',
+      type: 'string',
+      required: true,
+      default: {
+        '@path': '$.event'
+      }
+    },
+    properties: {
+      description: 'A list of key-value pairs that describe the event.',
+      label: 'Event Properties',
+      type: 'object',
+      required: false,
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  perform: (_hsq, event) => {
+    let { name, properties } = event.payload
+
+    if (event.settings.formatCustomBehavioralEventNames) {
+      name = `pe${event.settings.portalId}_${name.replace(/[\s.]+/g, '_').toLocaleLowerCase()}`
+    }
+
+    // for custom properties, we will:
+    // remove any non-primitives, replace spaces and dots with underscores, then lowercase
+    properties = properties && flatten(properties, '', [], (key) => key.replace(/[\s.]+/g, '_').toLocaleLowerCase())
+
+    _hsq.push(['trackCustomBehavioralEvent', { name, properties }])
+  }
+}
+
+export default action

package/src/trackPageView/__tests__/index.test.ts

@@ -0,0 +1,72 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import hubspotDestination, { destination } from '../../index'
+import { Hubspot } from '../../types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'trackPageView',
+    name: 'Track Page View',
+    enabled: true,
+    subscribe: 'type = "page"',
+    mapping: {
+      path: {
+        '@path': '$.context.page.path'
+      }
+    }
+  }
+]
+
+describe('Hubspot.trackPageView', () => {
+  const settings = {
+    portalId: '1234'
+  }
+
+  let mockHubspot: Hubspot
+  let trackPageViewEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [trackPageViewEventPlugin] = await hubspotDestination({
+      ...settings,
+      subscriptions
+    })
+    trackPageViewEvent = trackPageViewEventPlugin
+
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockHubspot = {
+        push: jest.fn()
+      }
+      return Promise.resolve(mockHubspot)
+    })
+    await trackPageViewEvent.load(Context.system(), {} as Analytics)
+  })
+
+  test('call both trackPageView and setPath', async () => {
+    const context = new Context({
+      type: 'page',
+      name: 'Fried Chicken 🍗',
+      category: 'Chicken Shop',
+      context: {
+        page: {
+          path: '/fried-chicken'
+        }
+      }
+    })
+    await trackPageViewEvent.track?.(context)
+    expect(mockHubspot.push).toHaveBeenCalledTimes(2)
+    expect(mockHubspot.push).toHaveBeenCalledWith(['trackPageView'])
+    expect(mockHubspot.push).toHaveBeenCalledWith(['setPath', '/fried-chicken'])
+  })
+
+  test('only calls trackPageView if no path is provided', async () => {
+    const context = new Context({
+      type: 'page',
+      name: 'Spicy Chicken Sandwich 🌶',
+      category: 'Chicken Shop'
+    })
+    await trackPageViewEvent.track?.(context)
+    expect(mockHubspot.push).toHaveBeenCalledTimes(1)
+    expect(mockHubspot.push).toHaveBeenCalledWith(['trackPageView'])
+  })
+})

package/src/trackPageView/generated-types.ts

@@ -0,0 +1,8 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The path of the current page. The set path will be treated as relative to the current domain being viewed.
+   */
+  path?: string
+}

package/src/trackPageView/index.ts

@@ -0,0 +1,28 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import { Hubspot } from '../types'
+import type { Payload } from './generated-types'
+
+const action: BrowserActionDefinition<Settings, Hubspot, Payload> = {
+  title: 'Track Page View',
+  description: 'Track the page view for the current page in HubSpot.',
+  defaultSubscription: 'type = "page"',
+  platform: 'web',
+  fields: {
+    path: {
+      description:
+        'The path of the current page. The set path will be treated as relative to the current domain being viewed.',
+      label: 'Path String',
+      type: 'string',
+      required: false
+    }
+  },
+  perform: (_hsq, event) => {
+    if (event.payload.path) {
+      _hsq.push(['setPath', event.payload.path])
+    }
+    _hsq.push(['trackPageView'])
+  }
+}
+
+export default action

package/src/types.ts

@@ -0,0 +1,3 @@
+export type Hubspot = {
+  push: (event: unknown[]) => void
+}

package/src/upsertContact/__tests__/index.test.ts

@@ -0,0 +1,207 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import { Subscription } from '@segment/browser-destination-runtime'
+import hubspotDestination, { destination } from '../../index'
+import { Hubspot } from '../../types'
+
+const subscriptions: Subscription[] = [
+  {
+    partnerAction: 'upsertContact',
+    name: 'Upsert Contact',
+    enabled: true,
+    subscribe: 'type = "identify"',
+    mapping: {
+      email: {
+        '@path': '$.traits.email'
+      },
+      custom_properties: {
+        '@path': '$.traits'
+      },
+      id: {
+        '@path': '$.userId'
+      },
+      company: {
+        '@path': '$.traits.company.name'
+      },
+      country: {
+        '@path': '$.traits.address.country'
+      },
+      state: {
+        '@path': '$.traits.address.state'
+      },
+      city: {
+        '@path': '$.traits.address.city'
+      },
+      address: {
+        '@path': '$.traits.address.street'
+      },
+      zip: {
+        '@path': '$.traits.address.postalCode'
+      }
+    }
+  }
+]
+
+describe('Hubspot.upsertContact', () => {
+  const settings = {
+    portalId: '1234',
+    formatCustomBehavioralEventNames: true
+  }
+
+  let mockHubspot: Hubspot
+  let upsertContactEvent: any
+  beforeEach(async () => {
+    jest.restoreAllMocks()
+
+    const [upsertContactEventPlugin] = await hubspotDestination({
+      ...settings,
+      subscriptions
+    })
+    upsertContactEvent = upsertContactEventPlugin
+
+    jest.spyOn(destination, 'initialize').mockImplementation(() => {
+      mockHubspot = {
+        push: jest.fn()
+      }
+      return Promise.resolve(mockHubspot)
+    })
+    await upsertContactEvent.load(Context.system(), {} as Analytics)
+  })
+
+  test('does not call Hubspot if there is no email', async () => {
+    const context = new Context({
+      type: 'identify',
+      userId: '👻',
+      traits: {
+        friendly: true
+      }
+    })
+
+    await upsertContactEvent.identify?.(context)
+    expect(mockHubspot.push).toHaveBeenCalledTimes(0)
+  })
+
+  test('Identifies the user to Hubspot when email is present', async () => {
+    const context = new Context({
+      type: 'identify',
+      userId: 'real_hubspot_tester',
+      traits: {
+        friendly: false,
+        email: 'real_hubspot_tester@jest_experts.com'
+      }
+    })
+
+    await upsertContactEvent.identify?.(context)
+    expect(mockHubspot.push).toHaveBeenCalledTimes(1)
+    expect(mockHubspot.push).toHaveBeenCalledWith([
+      'identify',
+      { email: 'real_hubspot_tester@jest_experts.com', id: 'real_hubspot_tester', friendly: false }
+    ])
+  })
+
+  test('populates company info from the traits', async () => {
+    const context = new Context({
+      type: 'identify',
+      userId: 'mike',
+      traits: {
+        friendly: false,
+        email: 'mike_eh@lph.com',
+        company: {
+          id: '123',
+          name: 'Los Pollos Hermanos',
+          industry: 'Transportation',
+          employee_count: 128,
+          plan: 'startup'
+        }
+      }
+    })
+
+    await upsertContactEvent.identify?.(context)
+    expect(mockHubspot.push).toHaveBeenCalledTimes(1)
+    expect(mockHubspot.push).toHaveBeenCalledWith([
+      'identify',
+      { email: 'mike_eh@lph.com', id: 'mike', friendly: false, company: 'Los Pollos Hermanos' }
+    ])
+  })
+
+  test('populates address info from the traits', async () => {
+    const context = new Context({
+      type: 'identify',
+      userId: 'mike',
+      traits: {
+        friendly: false,
+        email: 'mike_eh@lph.com',
+        address: {
+          street: '6th St',
+          city: 'San Francisco',
+          state: 'CA',
+          postalCode: '94103',
+          country: 'USA'
+        }
+      }
+    })
+
+    await upsertContactEvent.identify?.(context)
+    expect(mockHubspot.push).toHaveBeenCalledTimes(1)
+    expect(mockHubspot.push).toHaveBeenCalledWith([
+      'identify',
+      {
+        email: 'mike_eh@lph.com',
+        id: 'mike',
+        friendly: false,
+        address: '6th St',
+        country: 'USA',
+        state: 'CA',
+        city: 'San Francisco',
+        zip: '94103'
+      }
+    ])
+  })
+
+  test('flattens nested traits', async () => {
+    const context = new Context({
+      type: 'identify',
+      userId: 'mike',
+      traits: {
+        friendly: false,
+        email: 'mike_eh@lph.com',
+        address: {
+          street: '6th St',
+          city: 'San Francisco',
+          state: 'CA',
+          postalCode: '94103',
+          country: 'USA'
+        },
+        equipment: {
+          type: '🚘',
+          color: 'red',
+          make: {
+            make: 'Tesla',
+            model: 'Model S',
+            year: 2019
+          }
+        }
+      }
+    })
+
+    await upsertContactEvent.identify?.(context)
+    expect(mockHubspot.push).toHaveBeenCalledTimes(1)
+    expect(mockHubspot.push).toHaveBeenCalledWith([
+      'identify',
+      {
+        email: 'mike_eh@lph.com',
+        id: 'mike',
+        friendly: false,
+        address: '6th St',
+        country: 'USA',
+        state: 'CA',
+        city: 'San Francisco',
+        zip: '94103',
+        equipment_type: '🚘',
+        equipment_color: 'red',
+        equipment_make_make: 'Tesla',
+        equipment_make_model: 'Model S',
+        equipment_make_year: 2019
+      }
+    ])
+  })
+})

package/src/upsertContact/generated-types.ts

@@ -0,0 +1,42 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The contact’s email. Email is used to uniquely identify contact records in HubSpot and create or update the contact accordingly.
+   */
+  email: string
+  /**
+   * A custom external ID that identifies the visitor.
+   */
+  id?: string
+  /**
+   * A list of key-value pairs that describe the contact. Please see [HubSpot`s documentation](https://knowledge.hubspot.com/account/prevent-contact-properties-update-through-tracking-code-api) for limitations in updating contact properties.
+   */
+  custom_properties?: {
+    [k: string]: unknown
+  }
+  /**
+   * The name of the company the contact is associated with.
+   */
+  company?: string
+  /**
+   * The name of the country the contact is associated with.
+   */
+  country?: string
+  /**
+   * The name of the state the contact is associated with.
+   */
+  state?: string
+  /**
+   * The name of the city the contact is associated with.
+   */
+  city?: string
+  /**
+   * The street address of the contact.
+   */
+  address?: string
+  /**
+   * The postal code of the contact.
+   */
+  zip?: string
+}

package/src/upsertContact/index.ts

@@ -0,0 +1,121 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import { Hubspot } from '../types'
+import { flatten } from '../utils/flatten'
+
+const action: BrowserActionDefinition<Settings, Hubspot, Payload> = {
+  title: 'Upsert Contact',
+  description: 'Create or update a contact in HubSpot.',
+  defaultSubscription: 'type = "identify"',
+  platform: 'web',
+  fields: {
+    email: {
+      description:
+        'The contact’s email. Email is used to uniquely identify contact records in HubSpot and create or update the contact accordingly.',
+      label: 'Email Address',
+      type: 'string',
+      required: true,
+      default: {
+        '@path': '$.traits.email'
+      }
+    },
+    id: {
+      description: 'A custom external ID that identifies the visitor.',
+      label: 'External ID',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.userId'
+      }
+    },
+    custom_properties: {
+      description: 'A list of key-value pairs that describe the contact. Please see [HubSpot`s documentation](https://knowledge.hubspot.com/account/prevent-contact-properties-update-through-tracking-code-api) for limitations in updating contact properties.',
+      label: 'Custom Properties',
+      type: 'object',
+      required: false,
+      default: {
+        '@path': '$.traits'
+      }
+    },
+    company: {
+      description: 'The name of the company the contact is associated with.',
+      label: 'Company Name',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.traits.company.name'
+      }
+    },
+    country: {
+      description: 'The name of the country the contact is associated with.',
+      label: 'Country',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.traits.address.country'
+      }
+    },
+    state: {
+      description: 'The name of the state the contact is associated with.',
+      label: 'State',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.traits.address.state'
+      }
+    },
+    city: {
+      description: 'The name of the city the contact is associated with.',
+      label: 'City',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.traits.address.city'
+      }
+    },
+    address: {
+      description: 'The street address of the contact.',
+      label: 'Street Address',
+      type: 'string',
+      required: false,
+      default: {
+        '@path': '$.traits.address.street'
+      }
+    },
+    zip: {
+      description: 'The postal code of the contact.',
+      label: 'Postal Code',
+      type: 'string',
+      required: false,
+      default: {
+        '@if': {
+          exists: { '@path': '$.traits.address.postalCode' },
+          then: { '@path': '$.traits.address.postalCode' },
+          else: { '@path': '$.traits.address.postal_code' }
+        }
+      }
+    }
+  },
+  perform: (_hsq, event) => {
+    const payload = event.payload
+    if (!payload.email) {
+      return
+    }
+
+    // custom properties should be key-value pairs of strings, therefore, filtering out any non-primitive
+    const { custom_properties, ...rest } = payload
+    let flattenProperties
+    if (custom_properties) {
+      flattenProperties = flatten(custom_properties, '', ['address', 'company'])
+    }
+
+    _hsq.push(['identify', { ...flattenProperties, ...rest }])
+
+    if (event.settings.flushIdentifyImmediately) {
+      _hsq.push(['trackPageView'])
+    }
+  }
+}
+
+export default action

package/src/utils/flatten.ts

@@ -0,0 +1,30 @@
+import { JSONPrimitive } from '@segment/actions-core'
+
+export type Properties = {
+  [k: string]: unknown
+}
+
+type FlattenProperties = object & {
+  [k: string]: JSONPrimitive
+}
+
+export function flatten(
+  data: Properties,
+  prefix = '',
+  skipList: string[] = [],
+  keyTransformation = (input: string) => input
+): FlattenProperties {
+  let result: FlattenProperties = {}
+  for (const key in data) {
+    // skips flattening specific keys on the top level
+    if (!prefix && skipList.includes(key)) continue
+
+    if (typeof data[key] === 'object' && data[key] !== null) {
+      const flattened = flatten(data[key] as Properties, `${prefix}_${key}`, skipList, keyTransformation)
+      result = { ...result, ...flattened }
+    } else {
+      result[keyTransformation(`${prefix}_${key}`.replace(/^_/, ''))] = data[key] as JSONPrimitive
+    }
+  }
+  return result
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "baseUrl": "."
+  },
+  "include": ["src"],
+  "exclude": ["dist", "**/__tests__"]
+}