@segment/analytics-browser-actions-fullsession 1.1.0

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

@@ -0,0 +1,274 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import fullSessionDestination from '../../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+
+// Mock the browser destination runtime functions
+jest.mock('@segment/browser-destination-runtime/load-script', () => ({
+  loadScript: (_src: any, _attributes: any) => Promise.resolve()
+}))
+
+jest.mock('@segment/browser-destination-runtime/resolve-when', () => ({
+  resolveWhen: (_fn: any, _timeout: any) => Promise.resolve()
+}))
+
+// Mock the fullsession package
+jest.mock('fullsession', () => ({
+  fullSessionTracker: {
+    initialize: jest.fn(),
+    identify: jest.fn(),
+    setSessionAttributes: jest.fn(),
+    event: jest.fn()
+  }
+}))
+
+const trackSubscription: Subscription = {
+  partnerAction: 'recordEvent',
+  name: 'Record Event',
+  enabled: true,
+  subscribe: 'type = "track"',
+  mapping: {
+    name: {
+      '@path': '$.event'
+    },
+    properties: {
+      '@path': '$.properties'
+    }
+  }
+}
+
+describe('FullSession recordEvent action', () => {
+  const mockCustomerId = 'test-customer-id'
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    // Setup window.FUS mock if needed
+    if (typeof window !== 'undefined') {
+      // @ts-ignore
+      window.FUS = {}
+    }
+  })
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  test('should record event with name and properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [trackSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const eventName = 'Product Purchased'
+    const properties = {
+      product_id: 'ABC123',
+      product_name: 'Widget',
+      price: 29.99,
+      currency: 'USD',
+      category: 'Electronics'
+    }
+
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: eventName,
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.event).toHaveBeenCalledWith(eventName, properties)
+  })
+
+  test('should record event with only name', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [trackSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const eventName = 'Simple Event'
+
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: eventName
+      })
+    )
+
+    expect(fullSessionTracker.event).toHaveBeenCalledWith(eventName, {})
+  })
+
+  test('should record event with string and number properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [trackSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const eventName = 'Page View'
+    const properties = {
+      page_url: 'https://example.com/product/123',
+      page_title: 'Product Details',
+      load_time: 1.5,
+      session_id: 'sess_123',
+      user_count: 42
+    }
+
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: eventName,
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.event).toHaveBeenCalledWith(eventName, properties)
+  })
+
+  test('should handle empty properties object', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [trackSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const eventName = 'Button Clicked'
+
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: eventName,
+        properties: {}
+      })
+    )
+
+    expect(fullSessionTracker.event).toHaveBeenCalledWith(eventName, {})
+  })
+
+  test('should handle null properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [trackSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const eventName = 'Null Properties Event'
+
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: eventName,
+        properties: undefined
+      })
+    )
+
+    expect(fullSessionTracker.event).toHaveBeenCalledWith(eventName, {})
+  })
+
+  test('should record multiple events in sequence', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [trackSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    // First event
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: 'Event 1',
+        properties: { prop1: 'value1' }
+      })
+    )
+
+    // Second event
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: 'Event 2',
+        properties: { prop2: 'value2', count: 10 }
+      })
+    )
+
+    expect(fullSessionTracker.event).toHaveBeenCalledTimes(2)
+    expect(fullSessionTracker.event).toHaveBeenNthCalledWith(1, 'Event 1', { prop1: 'value1' })
+    expect(fullSessionTracker.event).toHaveBeenNthCalledWith(2, 'Event 2', { prop2: 'value2', count: 10 })
+  })
+
+  test('should record event with mixed property types', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [trackSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const eventName = 'Mixed Properties Event'
+    const properties = {
+      string_prop: 'test string',
+      number_prop: 123.45,
+      boolean_prop: true,
+      array_prop: [1, 2, 3],
+      object_prop: { nested: 'value' },
+      null_prop: null,
+      undefined_prop: undefined
+    }
+
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: eventName,
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.event).toHaveBeenCalledWith(eventName, properties)
+  })
+
+  test('should handle event with special characters in name', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [trackSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const eventName = 'Event with Special Characters! @#$%^&*()'
+    const properties = {
+      special_chars: 'åäöüñ',
+      unicode: '🎉🚀'
+    }
+
+    await event.track?.(
+      new Context({
+        type: 'track',
+        event: eventName,
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.event).toHaveBeenCalledWith(eventName, properties)
+  })
+})

package/src/recordEvent/generated-types.ts

@@ -0,0 +1,14 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * The name of the event being tracked.
+   */
+  name: string
+  /**
+   * Additional properties and metadata associated with the event.
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/recordEvent/index.ts

@@ -0,0 +1,37 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { FUS, CustomEventData } from '../types'
+
+const action: BrowserActionDefinition<Settings, FUS, Payload> = {
+  title: 'Track Event',
+  description: 'Track custom events and user interactions in FullSession for behavioral analysis.',
+  platform: 'web',
+  defaultSubscription: 'type = "track"',
+  fields: {
+    name: {
+      description: 'The name of the event being tracked.',
+      label: 'Event Name',
+      required: true,
+      type: 'string',
+      default: {
+        '@path': '$.event'
+      }
+    },
+    properties: {
+      description: 'Additional properties and metadata associated with the event.',
+      label: 'Event Properties',
+      required: false,
+      type: 'object',
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  perform: (FUS, data) => {
+    const { name, properties } = data.payload
+    FUS.event(name, (properties ?? {}) as CustomEventData)
+  }
+}
+
+export default action

package/src/types.ts

@@ -0,0 +1,14 @@
+import { fullSessionTracker } from 'fullsession'
+
+type CustomEventData = {
+  [key: string]: string | number
+  [stringKey: `${string}_str`]: string
+  [numberKey: `${string}_real`]: number
+}
+
+type UserCustomAttributes = {
+  [attribute: string]: string
+}
+
+export type FUS = typeof fullSessionTracker
+export { fullSessionTracker, CustomEventData, UserCustomAttributes }

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

@@ -0,0 +1,312 @@
+import { Analytics, Context } from '@segment/analytics-next'
+import fullSessionDestination from '../../index'
+import { Subscription } from '@segment/browser-destination-runtime/types'
+
+// Mock the browser destination runtime functions
+jest.mock('@segment/browser-destination-runtime/load-script', () => ({
+  loadScript: (_src: any, _attributes: any) => Promise.resolve()
+}))
+
+jest.mock('@segment/browser-destination-runtime/resolve-when', () => ({
+  resolveWhen: (_fn: any, _timeout: any) => Promise.resolve()
+}))
+
+// Mock the fullsession package
+jest.mock('fullsession', () => ({
+  fullSessionTracker: {
+    initialize: jest.fn(),
+    identify: jest.fn(),
+    setPageAttributes: jest.fn(),
+    event: jest.fn()
+  }
+}))
+
+const pageSubscription: Subscription = {
+  partnerAction: 'visitPage',
+  name: 'Visit Page',
+  enabled: true,
+  subscribe: 'type = "page"',
+  mapping: {
+    properties: {
+      '@path': '$.properties'
+    }
+  }
+}
+
+describe('FullSession visitPage action', () => {
+  const mockCustomerId = 'test-customer-id'
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    // Setup window.FUS mock if needed
+    if (typeof window !== 'undefined') {
+      // @ts-ignore
+      window.FUS = {}
+    }
+  })
+
+  test('should set session attributes with page properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const properties = {
+      title: 'Welcome to Our Site',
+      url: 'https://example.com',
+      path: '/',
+      referrer: 'https://google.com',
+      search: '?utm_source=google'
+    }
+
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'Home Page',
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({
+      ...properties
+    })
+  })
+
+  test('should handle page with category and properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const properties = {
+      title: 'Amazing Product',
+      url: 'https://example.com/products/amazing-product',
+      product_id: 'prod_123'
+    }
+
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'Product Details',
+        category: 'Products',
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({
+      ...properties
+    })
+  })
+
+  test('should handle page with properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const properties = {
+      title: 'About Our Company',
+      url: 'https://example.com/about',
+      section: 'company'
+    }
+
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'About Us',
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({
+      ...properties
+    })
+  })
+
+  test('should handle page with empty properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'Simple Page',
+        properties: {}
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({})
+  })
+
+  test('should handle page with null properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'Null Properties Page',
+        properties: undefined
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({})
+  })
+
+  test('should handle page without name and category', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const properties = {
+      title: 'Unnamed Page',
+      url: 'https://example.com/unnamed',
+      path: '/unnamed'
+    }
+
+    await event.page?.(
+      new Context({
+        type: 'page',
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({
+      ...properties
+    })
+  })
+
+  test('should handle complex properties with various data types', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const properties = {
+      title: 'Complex Page Title',
+      url: 'https://example.com/complex',
+      load_time: 2.5,
+      user_agent: 'Mozilla/5.0...',
+      is_authenticated: true,
+      visitor_count: 1500,
+      tags: ['homepage', 'featured'],
+      metadata: {
+        experiment_id: 'exp_123',
+        variant: 'A'
+      }
+    }
+
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'Complex Page',
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({
+      ...properties
+    })
+  })
+
+  test('should track multiple page visits in sequence', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    // First page visit
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'Home',
+        properties: { url: 'https://example.com' }
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({
+      url: 'https://example.com'
+    })
+
+    // Second page visit
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'Products',
+        properties: { url: 'https://example.com/products' }
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({
+      url: 'https://example.com/products'
+    })
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledTimes(2)
+  })
+
+  test('should handle page visit with special characters in properties', async () => {
+    const { fullSessionTracker } = await import('fullsession')
+
+    const [event] = await fullSessionDestination({
+      customerId: mockCustomerId,
+      subscriptions: [pageSubscription] as any
+    })
+
+    await event.load(Context.system(), {} as Analytics)
+
+    const properties = {
+      title: 'Title with émojis 🚀 and symbols!',
+      url: 'https://example.com/special-chars?q=test&lang=en',
+      description: 'A page with special characters: àáâãäåæçèéêë'
+    }
+
+    await event.page?.(
+      new Context({
+        type: 'page',
+        name: 'Page with "Special" Characters & Symbols',
+        properties
+      })
+    )
+
+    expect(fullSessionTracker.setPageAttributes).toHaveBeenCalledWith({
+      ...properties
+    })
+  })
+})

package/src/visitPage/generated-types.ts

@@ -0,0 +1,10 @@
+// Generated file. DO NOT MODIFY IT BY HAND.
+
+export interface Payload {
+  /**
+   * Properties and metadata associated with the page being viewed
+   */
+  properties?: {
+    [k: string]: unknown
+  }
+}

package/src/visitPage/index.ts

@@ -0,0 +1,31 @@
+import type { BrowserActionDefinition } from '@segment/browser-destination-runtime/types'
+import type { Settings } from '../generated-types'
+import type { Payload } from './generated-types'
+import type { FUS, UserCustomAttributes } from '../types'
+
+// Change from unknown to the partner SDK types
+const action: BrowserActionDefinition<Settings, FUS, Payload> = {
+  title: 'Page View',
+  description: 'Track page views and set page-specific attributes in FullSession for navigation analysis.',
+  defaultSubscription: 'type = "page"',
+  platform: 'web',
+  fields: {
+    properties: {
+      type: 'object',
+      required: false,
+      description: 'Properties and metadata associated with the page being viewed',
+      label: 'Page Properties',
+      default: {
+        '@path': '$.properties'
+      }
+    }
+  },
+  perform: (FUS, data) => {
+    const { properties } = data.payload
+    FUS.setPageAttributes({
+      ...properties
+    } as UserCustomAttributes)
+  }
+}
+
+export default action

package/tsconfig.json

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