@segment/analytics-browser-actions-friendbuy 1.0.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@segment/analytics-browser-actions-friendbuy",
+  "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/actions-shared": "^1.53.0",
+    "@segment/browser-destination-runtime": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@segment/analytics-next": "*"
+  }
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,38 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import friendbuyDestination, { destination } from '../index'
+import nock from 'nock'
+
+const subscriptions = [
+  {
+    partnerAction: 'trackCustomer',
+    name: 'Track Customer',
+    enabled: true,
+    subscribe: 'type = "identify"',
+    mapping: {}
+  }
+]
+
+describe('Friendbuy', () => {
+  const merchantId = '0ebece2e-b04c-4504-97f2-16cd9f423612'
+
+  test('loading', async () => {
+    jest.spyOn(destination, 'initialize')
+
+    nock('https://static.fbot.me').get('/friendbuy.js').reply(200, {})
+    nock('https://campaign.fbot.me')
+      .get(/^\/[^/]*\/campaigns.js$/)
+      .reply(200, {})
+
+    const [event] = await friendbuyDestination({
+      merchantId,
+      subscriptions
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+    expect(destination.initialize).toHaveBeenCalled()
+
+    const expectedFriendbuyAPI = [['merchant', merchantId]] as any
+    expectedFriendbuyAPI.merchantId = merchantId
+    expect(window.friendbuyAPI).toEqual(expectedFriendbuyAPI)
+  })
+})

package/src/generated-types.ts

@@ -0,0 +1,8 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Settings {
+  /**
+   * Find your Friendbuy Merchant ID by logging in to your [Friendbuy account](https://retailer.friendbuy.io/) and going to Developer Center > Friendbuy Code.
+   */
+  merchantId: string
+}

package/src/index.ts

@@ -0,0 +1,91 @@
+import type { BrowserDestinationDefinition } from '@segment/browser-destination-runtime/types'
+import type { DestinationDefinition } from '@segment/actions-core'
+import { browserDestination } from '@segment/browser-destination-runtime/shim'
+import { defaultValues } from '@segment/actions-core'
+
+import type { Settings } from './generated-types'
+import type { FriendbuyAPI } from './types'
+import trackCustomer, { trackCustomerDefaultSubscription } from './trackCustomer'
+import trackPurchase, { browserTrackPurchaseFields, trackPurchaseDefaultSubscription } from './trackPurchase'
+import trackSignUp, { browserTrackSignUpFields, trackSignUpDefaultSubscription } from './trackSignUp'
+import trackPage, { trackPageDefaultSubscription, trackPageFields } from './trackPage'
+import trackCustomEvent from './trackCustomEvent'
+import { trackCustomerFields } from '@segment/actions-shared'
+
+declare global {
+  interface Window {
+    friendbuyAPI?: FriendbuyAPI
+    friendbuyBaseHost?: string
+  }
+}
+
+// Presets are shown in Segment configuration flow as "Pre-Built Subscriptions".
+const presets: DestinationDefinition['presets'] = [
+  {
+    name: 'Track Customer',
+    subscribe: trackCustomerDefaultSubscription,
+    partnerAction: 'trackCustomer',
+    mapping: defaultValues(trackCustomerFields)
+  },
+  {
+    name: 'Track Purchase',
+    subscribe: trackPurchaseDefaultSubscription,
+    partnerAction: 'trackPurchase',
+    mapping: defaultValues(browserTrackPurchaseFields)
+  },
+  {
+    name: 'Track Sign Up',
+    subscribe: trackSignUpDefaultSubscription,
+    partnerAction: 'trackSignUp',
+    mapping: defaultValues(browserTrackSignUpFields)
+  },
+  {
+    name: 'Track Page',
+    subscribe: trackPageDefaultSubscription,
+    partnerAction: 'trackPage',
+    mapping: defaultValues(trackPageFields)
+  }
+]
+
+export const destination: BrowserDestinationDefinition<Settings, FriendbuyAPI> = {
+  name: 'Friendbuy (Actions)',
+  slug: 'actions-friendbuy',
+  mode: 'device',
+
+  settings: {
+    merchantId: {
+      label: 'Friendbuy Merchant ID',
+      description:
+        'Find your Friendbuy Merchant ID by logging in to your [Friendbuy account](https://retailer.friendbuy.io/) and going to Developer Center > Friendbuy Code.',
+      type: 'string',
+      format: 'uuid',
+      required: true
+    }
+  },
+
+  initialize: async ({ settings /* , analytics */ }, dependencies) => {
+    let friendbuyAPI: FriendbuyAPI
+    window.friendbuyAPI = friendbuyAPI = window.friendbuyAPI || ([] as unknown as FriendbuyAPI)
+    const friendbuyBaseHost = window.friendbuyBaseHost ?? 'fbot.me'
+
+    friendbuyAPI.merchantId = settings.merchantId
+    friendbuyAPI.push(['merchant', settings.merchantId])
+
+    // The Friendbuy JavaScript can be loaded asynchronously.
+    void dependencies.loadScript(`https://static.${friendbuyBaseHost}/friendbuy.js`)
+    void dependencies.loadScript(`https://campaign.${friendbuyBaseHost}/${settings.merchantId}/campaigns.js`)
+
+    return friendbuyAPI
+  },
+
+  presets,
+  actions: {
+    trackCustomer,
+    trackPurchase,
+    trackSignUp,
+    trackPage,
+    trackCustomEvent
+  }
+}
+
+export default browserDestination(destination)

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

@@ -0,0 +1,98 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import friendbuyDestination from '../../index'
+import trackCustomEventObject, { browserTrackCustomEventFields } from '../index'
+
+import { loadScript } from '@segment/browser-destination-runtime/load-script'
+jest.mock('@segment/browser-destination-runtime/load-script')
+beforeEach(async () => {
+  // Prevent friendbuy.js and campaigns.js from being loaded.
+  ;(loadScript as jest.Mock).mockResolvedValue(true)
+})
+
+describe('Friendbuy.trackCustomEvent', () => {
+  const subscriptions = [
+    {
+      partnerAction: 'trackCustomEvent',
+      name: trackCustomEventObject.title,
+      enabled: true,
+      subscribe: 'type = "track" and event = "download"',
+      mapping: Object.fromEntries(
+        Object.entries(browserTrackCustomEventFields).map(([name, value]) => [name, value.default])
+      )
+    }
+  ]
+
+  test('all fields', async () => {
+    const merchantId = '1993d0f1-8206-4336-8c88-64e170f2419e'
+
+    const [trackCustomEvent] = await friendbuyDestination({
+      merchantId,
+      subscriptions
+    })
+    // console.log('trackCustomEvent', JSON.stringify(trackCustomEvent, null, 2), trackCustomEvent)
+    expect(trackCustomEvent).toBeDefined()
+
+    await trackCustomEvent.load(Context.system(), {} as Analytics)
+
+    // console.log(window.friendbuyAPI)
+    jest.spyOn(window.friendbuyAPI as any, 'push')
+
+    {
+      // Non-download events are not sent.
+      const context1 = new Context({
+        type: 'track',
+        event: 'upload',
+        properties: { type: 'application', fileId: 'MyApp', deduplicationId: '1234' }
+      })
+
+      trackCustomEvent.track?.(context1)
+
+      expect(window.friendbuyAPI?.push).not.toHaveBeenCalled()
+    }
+
+    {
+      // Download events are sent.
+      const context2 = new Context({
+        type: 'track',
+        event: 'download',
+        properties: { type: 'application', fileId: 'MyApp', deduplicationId: '1234' }
+      })
+
+      trackCustomEvent.track?.(context2)
+
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(1, [
+        'track',
+        'download',
+        { type: 'application', fileId: 'MyApp', deduplicationId: '1234' }
+      ])
+    }
+
+    {
+      // Customer is sent if customer fields are present.
+      const userId = 'john-doe-1234'
+      const anonymousId = '960efa33-6d3b-4eb9-a4e7-d95412d9829e'
+      const email = 'john.doe@example.com'
+      const firstName = 'John'
+      const lastName = 'Doe'
+      const context3 = new Context({
+        type: 'track',
+        event: 'download',
+        userId,
+        anonymousId,
+        properties: { type: 'application', fileId: 'MyApp', email, firstName, lastName }
+      })
+
+      trackCustomEvent.track?.(context3)
+
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(2, [
+        'track',
+        'download',
+        {
+          type: 'application',
+          fileId: 'MyApp',
+          customer: { id: userId, anonymousId, email, firstName, lastName, name: `${firstName} ${lastName}` }
+        }
+      ])
+    }
+  })
+})

package/src/trackCustomEvent/generated-types.ts

@@ -0,0 +1,30 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The type of the event to track.
+   */
+  eventType: string
+  /**
+   * Object containing the properties for the event being tracked. All of the fields in this object will be sent in the root of the Friendbuy track event.
+   */
+  eventProperties: {
+    [k: string]: unknown
+  }
+  /**
+   * An identifier for the event being tracked to prevent the same event from being rewarded more than once.
+   */
+  deduplicationId?: string
+  /**
+   * The user's customer ID.
+   */
+  customerId: string
+  /**
+   * The user's anonymous id
+   */
+  anonymousId?: string
+  /**
+   * The user's email address.
+   */
+  email?: string
+}

package/src/trackCustomEvent/index.ts

@@ -0,0 +1,49 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+
+import type { FriendbuyAPI } from '../types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { ConvertFun, EventMap } from '@segment/actions-shared'
+
+import { AnalyticsPayload, COPY, DROP, ROOT, mapEvent } from '@segment/actions-shared'
+import { trackCustomEventFields } from '@segment/actions-shared'
+import { addName, enjoinInteger, enjoinString, moveEventPropertiesToRoot, parseDate } from '@segment/actions-shared'
+
+export const browserTrackCustomEventFields = trackCustomEventFields({}) // @@ email required?
+
+const trackCustomEventPub: EventMap = {
+  fields: {
+    eventType: DROP,
+    deduplicationId: COPY,
+
+    // CUSTOMER FIELDS
+    customerId: { name: ['customer', 'id'], convert: enjoinString as ConvertFun },
+    anonymousId: { name: ['customer', 'anonymousId'] },
+    email: { name: ['customer', 'email'] },
+    isNewCustomer: { name: ['customer', 'isNewCustomer'] },
+    loyaltyStatus: { name: ['customer', 'loyaltyStatus'] },
+    firstName: { name: ['customer', 'firstName'] },
+    lastName: { name: ['customer', 'lastName'] },
+    name: { name: ['customer', 'name'] },
+    age: { name: ['customer', 'age'], convert: enjoinInteger as ConvertFun },
+    birthday: { name: ['customer', 'birthday'], convert: parseDate as ConvertFun }
+  },
+  unmappedFieldObject: ROOT
+}
+
+const action: BrowserActionDefinition<Settings, FriendbuyAPI, Payload> = {
+  title: 'Track Custom Event',
+  description: 'Record when a customer completes any custom event that you define.',
+  // trackCustomEvent has no default subscription.
+  platform: 'web',
+  fields: browserTrackCustomEventFields,
+
+  perform: (friendbuyAPI, { payload }) => {
+    const analyticsPayload = moveEventPropertiesToRoot(payload as unknown as AnalyticsPayload)
+    addName(analyticsPayload)
+    const friendbuyPayload = mapEvent(trackCustomEventPub, analyticsPayload)
+    friendbuyAPI.push(['track', payload.eventType, friendbuyPayload])
+  }
+}
+
+export default action

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

@@ -0,0 +1,196 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import friendbuyDestination from '../../index'
+import trackCustomerObject, { trackCustomerDefaultSubscription } from '../index'
+import { trackCustomerFields } from '@segment/actions-shared'
+
+import { loadScript } from '@segment/browser-destination-runtime/load-script'
+jest.mock('@segment/browser-destination-runtime/load-script')
+beforeEach(async () => {
+  // Prevent friendbuy.js and campaigns.js from being loaded.
+  ;(loadScript as jest.Mock).mockResolvedValue(true)
+})
+
+describe('Friendbuy.trackCustomer', () => {
+  // console.log('trackCustomer', JSON.stringify(trackCustomer, null, 2))
+
+  const subscriptions = [
+    {
+      partnerAction: 'trackCustomer',
+      name: trackCustomerObject.title,
+      enabled: true,
+      subscribe: trackCustomerDefaultSubscription,
+      mapping: Object.fromEntries(
+        Object.entries(trackCustomerFields)
+          .map(([name, value]) => [name, value.default])
+          .concat(
+            ['customerSince', 'loyaltyStatus', 'isNewCustomer'].map((name) => [name, { '@path': `$.traits.${name}` }])
+          )
+      )
+    }
+  ]
+
+  // console.log('subscriptions', JSON.stringify(subscriptions, null, 2))
+
+  test('all fields', async () => {
+    const merchantId = '1993d0f1-8206-4336-8c88-64e170f2419e'
+    const userId = 'john-doe-12345'
+    const anonymousId = '18aedb99-e756-40fa-8e83-d35f90998fb4'
+    const customerSince = '2021-10-20T14:20:15Z'
+    const isNewCustomer = false
+    const loyaltyStatus = 'in'
+    const firstName = 'John'
+    const lastName = 'Doe'
+    const name = `${firstName} ${lastName}`
+    const email = 'john.doe@example.com'
+    const age = 25
+    const birthday = '1996-02-29'
+    const language = 'en-US'
+    const country = 'US'
+    const state = 'CA'
+    const city = 'Beverly Hills'
+    const zipCode = '90210'
+    const friendbuyAttributes = { custom1: 'custom1', custom2: 'custom2' }
+
+    const [trackCustomer] = await friendbuyDestination({
+      merchantId,
+      subscriptions
+    })
+    // console.log('trackCustomer', JSON.stringify(trackCustomer, null, 2), trackCustomer)
+    expect(trackCustomer).toBeDefined()
+
+    await trackCustomer.load(Context.system(), {} as Analytics)
+
+    // console.log(window.friendbuyAPI)
+    jest.spyOn(window.friendbuyAPI as any, 'push')
+
+    {
+      // all fields
+      const context1 = new Context({
+        type: 'identify',
+        userId,
+        anonymousId,
+        traits: {
+          email,
+          customerSince,
+          isNewCustomer,
+          loyaltyStatus,
+          firstName,
+          lastName,
+          name,
+          age,
+          birthday,
+          language,
+          address: { country, state, city, postalCode: zipCode },
+          friendbuyAttributes
+        }
+      })
+      // console.log('context1', JSON.stringify(context1, null, 2))
+
+      trackCustomer.identify?.(context1)
+
+      // console.log('trackCustomer request', JSON.stringify(window.friendbuyAPI.push.mock.calls[0], null, 2))
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(1, [
+        'track',
+        'customer',
+        {
+          id: userId,
+          email,
+          customerSince,
+          isNewCustomer,
+          loyaltyStatus,
+          firstName,
+          lastName,
+          name,
+          age,
+          birthday: { year: 1996, month: 2, day: 29 },
+          language,
+          country,
+          state,
+          city,
+          zipCode,
+          anonymousId,
+          ...friendbuyAttributes
+        },
+        true
+      ])
+    }
+
+    {
+      // name derived from firstName and lastName
+      const context2 = new Context({
+        type: 'identify',
+        userId,
+        traits: {
+          firstName,
+          lastName
+        }
+      })
+
+      trackCustomer.identify?.(context2)
+
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(2, [
+        'track',
+        'customer',
+        {
+          id: userId,
+          firstName,
+          lastName,
+          name
+        },
+        true
+      ])
+    }
+
+    {
+      // name without firstName and lastName
+      const context3 = new Context({
+        type: 'identify',
+        userId,
+        traits: {
+          email,
+          name
+        }
+      })
+
+      trackCustomer.identify?.(context3)
+
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(3, [
+        'track',
+        'customer',
+        {
+          id: userId,
+          email,
+          name
+        },
+        true
+      ])
+    }
+
+    {
+      // enjoined fields are converted
+      const context4 = new Context({
+        type: 'identify',
+        userId: 12345,
+        traits: {
+          email,
+          age: '44',
+          address: { postalCode: 90210 }
+        }
+      })
+
+      trackCustomer.identify?.(context4)
+
+      expect(window.friendbuyAPI?.push).toHaveBeenNthCalledWith(4, [
+        'track',
+        'customer',
+        {
+          id: '12345',
+          email,
+          age: 44,
+          zipCode: '90210'
+        },
+        true
+      ])
+    }
+  })
+})

package/src/trackCustomer/generated-types.ts

@@ -0,0 +1,74 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The user's customer ID.
+   */
+  customerId: string
+  /**
+   * The user's anonymous id.
+   */
+  anonymousId?: string
+  /**
+   * The user's email address.
+   */
+  email: string
+  /**
+   * The user's given name.
+   */
+  firstName?: string
+  /**
+   * The user's surname.
+   */
+  lastName?: string
+  /**
+   * The user's full name. If the name trait doesn't exist then it will be automatically derived from the firstName and lastName traits if they are defined.
+   */
+  name?: string
+  /**
+   * The user's age.
+   */
+  age?: number
+  /**
+   * The user's birthday in the format "YYYY-MM-DD", or "0000-MM-DD" to omit the year.
+   */
+  birthday?: string
+  /**
+   * The user's language.
+   */
+  language?: string
+  /**
+   * The user's country.
+   */
+  addressCountry?: string
+  /**
+   * The user's state.
+   */
+  addressState?: string
+  /**
+   * The user's city.
+   */
+  addressCity?: string
+  /**
+   * The user's postal code.
+   */
+  addressPostalCode?: string
+  /**
+   * The date the user became a customer.
+   */
+  customerSince?: string
+  /**
+   * The status of the user in your loyalty program. Valid values are "in", "out", or "blocked".
+   */
+  loyaltyStatus?: string
+  /**
+   * Flag to indicate whether the user is a new customer.
+   */
+  isNewCustomer?: boolean
+  /**
+   * Custom attributes to send to Friendbuy. You should pass an object whose keys are the names of the custom attributes and whose values are strings. Non-string-valued attributes will be dropped.
+   */
+  friendbuyAttributes?: {
+    [k: string]: unknown
+  }
+}

package/src/trackCustomer/index.ts

@@ -0,0 +1,51 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+
+import type { FriendbuyAPI } from '../types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { AnalyticsPayload, ConvertFun, EventMap } from '@segment/actions-shared'
+
+import { COPY, ROOT, mapEvent } from '@segment/actions-shared'
+import { trackCustomerFields } from '@segment/actions-shared'
+import { addName, enjoinInteger, enjoinString, parseDate } from '@segment/actions-shared'
+
+// see https://segment.com/docs/config-api/fql/
+export const trackCustomerDefaultSubscription = 'type = "identify"'
+
+const trackCustomerPub: EventMap = {
+  fields: {
+    customerId: { name: 'id', convert: enjoinString as ConvertFun },
+    anonymousID: COPY,
+    email: COPY,
+    isNewCustomer: COPY,
+    loyaltyStatus: COPY,
+    firstName: COPY,
+    lastName: COPY,
+    name: COPY,
+    age: { convert: enjoinInteger as ConvertFun },
+    // fbt-merchant-api complains about birthday being an object but passes it anyway.
+    birthday: { convert: parseDate as ConvertFun },
+    language: COPY,
+    addressCountry: { name: 'country' },
+    addressState: { name: 'state' },
+    addressCity: { name: 'city' },
+    addressPostalCode: { name: 'zipCode', convert: enjoinString as ConvertFun }
+  },
+  unmappedFieldObject: ROOT
+}
+
+const action: BrowserActionDefinition<Settings, FriendbuyAPI, Payload> = {
+  title: 'Track Customer',
+  description: 'Create a new customer profile or update an existing customer profile.',
+  defaultSubscription: trackCustomerDefaultSubscription,
+  platform: 'web',
+  fields: trackCustomerFields,
+
+  perform: (friendbuyAPI, { payload }) => {
+    addName(payload)
+    const friendbuyPayload = mapEvent(trackCustomerPub, payload as unknown as AnalyticsPayload)
+    friendbuyAPI.push(['track', 'customer', friendbuyPayload, true])
+  }
+}
+
+export default action