@hanzo/insights-react 1.8.1

package/src/context/__tests__/PostHogProvider.test.tsx

@@ -0,0 +1,131 @@
+import * as React from 'react'
+import { render, act } from '@testing-library/react'
+import { PostHogProvider, PostHog } from '..'
+import posthogJs from '@hanzo/insights'
+
+// Mock posthog-js
+jest.mock('@hanzo/insights', () => ({
+    __esModule: true,
+    default: {
+        init: jest.fn(),
+        set_config: jest.fn(),
+        __loaded: false,
+    },
+}))
+
+describe('PostHogProvider component', () => {
+    it('should render children components', () => {
+        const posthog = {} as unknown as PostHog
+        const { getByText } = render(
+            <PostHogProvider client={posthog}>
+                <div>Test</div>
+            </PostHogProvider>
+        )
+        expect(getByText('Test')).toBeTruthy()
+    })
+
+    describe('when using apiKey initialization', () => {
+        const apiKey = 'test-api-key'
+        const initialOptions = { api_host: 'https://app.posthog.com' }
+        const updatedOptions = { api_host: 'https://eu.posthog.com' }
+
+        beforeEach(() => {
+            jest.clearAllMocks()
+        })
+
+        it('should call set_config when options change', () => {
+            const { rerender } = render(
+                <PostHogProvider apiKey={apiKey} options={initialOptions}>
+                    <div>Test</div>
+                </PostHogProvider>
+            )
+
+            // First render should initialize
+            expect(posthogJs.init).toHaveBeenCalledWith(apiKey, initialOptions)
+
+            // Rerender with new options
+            act(() => {
+                rerender(
+                    <PostHogProvider apiKey={apiKey} options={updatedOptions}>
+                        <div>Test</div>
+                    </PostHogProvider>
+                )
+            })
+
+            // Should call set_config with new options
+            expect(posthogJs.set_config).toHaveBeenCalledWith(updatedOptions)
+        })
+
+        it('should NOT call set_config when we pass new options that are the same as the previous options', () => {
+            const { rerender } = render(
+                <PostHogProvider apiKey={apiKey} options={initialOptions}>
+                    <div>Test</div>
+                </PostHogProvider>
+            )
+
+            // First render should initialize
+            expect(posthogJs.init).toHaveBeenCalledWith(apiKey, initialOptions)
+
+            // Rerender with new options
+            const sameOptionsButDifferentReference = { ...initialOptions }
+            act(() => {
+                rerender(
+                    <PostHogProvider apiKey={apiKey} options={sameOptionsButDifferentReference}>
+                        <div>Test</div>
+                    </PostHogProvider>
+                )
+            })
+
+            // Should NOT call set_config
+            expect(posthogJs.set_config).not.toHaveBeenCalled()
+        })
+
+        it('should warn when attempting to change apiKey', () => {
+            const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+            const newApiKey = 'different-api-key'
+
+            const { rerender } = render(
+                <PostHogProvider apiKey={apiKey} options={initialOptions}>
+                    <div>Test</div>
+                </PostHogProvider>
+            )
+
+            // First render should initialize
+            expect(posthogJs.init).toHaveBeenCalledWith(apiKey, initialOptions)
+
+            // Rerender with new apiKey
+            act(() => {
+                rerender(
+                    <PostHogProvider apiKey={newApiKey} options={initialOptions}>
+                        <div>Test</div>
+                    </PostHogProvider>
+                )
+            })
+
+            // Should warn about apiKey change
+            expect(consoleSpy).toHaveBeenCalledWith(
+                expect.stringContaining('You have provided a different `apiKey` to `PostHogProvider`')
+            )
+
+            consoleSpy.mockRestore()
+        })
+
+        it('warns if posthogJs has been loaded elsewhere', () => {
+            ;(posthogJs as any).__loaded = true
+
+            const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+            render(
+                <PostHogProvider apiKey={apiKey} options={initialOptions}>
+                    <div>Test</div>
+                </PostHogProvider>
+            )
+
+            expect(consoleSpy).toHaveBeenCalledWith(
+                expect.stringContaining('`posthog` was already loaded elsewhere. This may cause issues.')
+            )
+
+            consoleSpy.mockRestore()
+            ;(posthogJs as any).__loaded = false
+        })
+    })
+})

package/src/context/index.ts

@@ -0,0 +1,2 @@
+export * from './PostHogContext'
+export * from './PostHogProvider'

package/src/helpers/error-helpers.ts

@@ -0,0 +1,15 @@
+import type { ErrorInfo } from 'react'
+import { PostHog } from '../context'
+import { CaptureResult } from '@hanzo/insights'
+
+export const setupReactErrorHandler = (
+    client: PostHog,
+    callback?: (event: CaptureResult | undefined, error: any, errorInfo: ErrorInfo) => void
+) => {
+    return (error: any, errorInfo: ErrorInfo): void => {
+        const event = client.captureException(error)
+        if (callback) {
+            callback(event, error, errorInfo)
+        }
+    }
+}

package/src/helpers/index.ts

@@ -0,0 +1 @@
+export * from './error-helpers'

package/src/hooks/__tests__/featureFlags.test.tsx

@@ -0,0 +1,273 @@
+import * as React from 'react'
+import { renderHook, act } from '@testing-library/react'
+import { PostHogProvider, PostHog } from '../../context'
+import { isUndefined } from '../../utils/type-utils'
+import {
+    useFeatureFlagPayload,
+    useFeatureFlagVariantKey,
+    useFeatureFlagEnabled,
+    useFeatureFlagResult,
+    useActiveFeatureFlags,
+} from '../index'
+
+jest.useFakeTimers()
+
+const ACTIVE_FEATURE_FLAGS = ['example_feature_true', 'multivariate_feature', 'example_feature_payload']
+
+const FEATURE_FLAG_STATUS: Record<string, string | boolean> = {
+    example_feature_true: true,
+    example_feature_false: false,
+    multivariate_feature: 'string-value',
+    example_feature_payload: 'test',
+}
+
+const FEATURE_FLAG_PAYLOADS: Record<string, any> = {
+    example_feature_payload: {
+        id: 1,
+        name: 'example_feature_1_payload',
+        key: 'example_feature_1_payload',
+    },
+}
+
+describe('feature flag hooks', () => {
+    let posthog: PostHog
+    let renderProvider: React.FC<{ children: React.ReactNode }>
+
+    beforeEach(() => {
+        posthog = {
+            isFeatureEnabled: (flag: string) => !!FEATURE_FLAG_STATUS[flag],
+            getFeatureFlag: (flag: string) => FEATURE_FLAG_STATUS[flag],
+            getFeatureFlagPayload: (flag: string) => FEATURE_FLAG_PAYLOADS[flag],
+            getFeatureFlagResult: (flag: string) => {
+                const value = FEATURE_FLAG_STATUS[flag]
+                if (isUndefined(value)) {
+                    return undefined
+                }
+                return {
+                    key: flag,
+                    enabled: !!value,
+                    variant: typeof value === 'string' ? value : undefined,
+                    payload: FEATURE_FLAG_PAYLOADS[flag],
+                }
+            },
+            onFeatureFlags: (callback: any) => {
+                const activeFlags: string[] = []
+                for (const flag in FEATURE_FLAG_STATUS) {
+                    if (FEATURE_FLAG_STATUS[flag]) {
+                        activeFlags.push(flag)
+                    }
+                }
+                callback(activeFlags)
+                return () => {}
+            },
+            featureFlags: {
+                getFlags: () => ACTIVE_FEATURE_FLAGS,
+                hasLoadedFlags: true,
+            } as unknown as PostHog['featureFlags'],
+        } as unknown as PostHog
+
+        // eslint-disable-next-line react/display-name
+        renderProvider = ({ children }) => <PostHogProvider client={posthog}>{children}</PostHogProvider>
+    })
+
+    it.each([
+        ['example_feature_true', true],
+        ['example_feature_false', false],
+        ['missing', false],
+        ['multivariate_feature', true],
+        ['example_feature_payload', true],
+    ])('should get the boolean feature flag', (flag, expected) => {
+        const { result } = renderHook(() => useFeatureFlagEnabled(flag), {
+            wrapper: renderProvider,
+        })
+        expect(result.current).toEqual(expected)
+    })
+
+    it.each([
+        ['example_feature_true', undefined],
+        ['example_feature_false', undefined],
+        ['missing', undefined],
+        ['multivariate_feature', undefined],
+        ['example_feature_payload', FEATURE_FLAG_PAYLOADS.example_feature_payload],
+    ])('should get the payload feature flag', (flag, expected) => {
+        const { result } = renderHook(() => useFeatureFlagPayload(flag), {
+            wrapper: renderProvider,
+        })
+        expect(result.current).toEqual(expected)
+    })
+
+    it('should return the active feature flags', () => {
+        const { result } = renderHook(() => useActiveFeatureFlags(), {
+            wrapper: renderProvider,
+        })
+        expect(result.current).toEqual(['example_feature_true', 'multivariate_feature', 'example_feature_payload'])
+    })
+
+    it.each([
+        ['example_feature_true', true],
+        ['example_feature_false', false],
+        ['missing', undefined],
+        ['multivariate_feature', 'string-value'],
+    ])('should get the feature flag variant key', (flag, expected) => {
+        const { result } = renderHook(() => useFeatureFlagVariantKey(flag), {
+            wrapper: renderProvider,
+        })
+        expect(result.current).toEqual(expected)
+    })
+
+    describe('useFeatureFlagResult', () => {
+        describe('bootstrap fallback', () => {
+            function renderWithBootstrap(
+                bootstrapFlags: Record<string, string | boolean>,
+                bootstrapPayloads?: Record<string, any>
+            ) {
+                const client = {
+                    getFeatureFlagResult: () => undefined,
+                    onFeatureFlags: () => () => {},
+                    config: {
+                        bootstrap: {
+                            featureFlags: bootstrapFlags,
+                            featureFlagPayloads: bootstrapPayloads,
+                        },
+                    },
+                    featureFlags: {
+                        hasLoadedFlags: false,
+                    } as unknown as PostHog['featureFlags'],
+                } as unknown as PostHog
+
+                // eslint-disable-next-line react/display-name
+                const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+                    <PostHogProvider client={client}>{children}</PostHogProvider>
+                )
+
+                return wrapper
+            }
+
+            it('returns result for a boolean bootstrap flag', () => {
+                const wrapper = renderWithBootstrap({ my_flag: true })
+                const { result } = renderHook(() => useFeatureFlagResult('my_flag'), { wrapper })
+                expect(result.current).toEqual({
+                    key: 'my_flag',
+                    enabled: true,
+                    variant: undefined,
+                    payload: undefined,
+                })
+            })
+
+            it('returns result for a multivariate bootstrap flag', () => {
+                const wrapper = renderWithBootstrap({ my_flag: 'variant-a' })
+                const { result } = renderHook(() => useFeatureFlagResult('my_flag'), { wrapper })
+                expect(result.current).toEqual({
+                    key: 'my_flag',
+                    enabled: true,
+                    variant: 'variant-a',
+                    payload: undefined,
+                })
+            })
+
+            it('returns result for a disabled bootstrap flag', () => {
+                const wrapper = renderWithBootstrap({ my_flag: false })
+                const { result } = renderHook(() => useFeatureFlagResult('my_flag'), { wrapper })
+                expect(result.current).toEqual({
+                    key: 'my_flag',
+                    enabled: false,
+                    variant: undefined,
+                    payload: undefined,
+                })
+            })
+
+            it('includes payload from bootstrap data', () => {
+                const payload = { color: 'blue' }
+                const wrapper = renderWithBootstrap({ my_flag: true }, { my_flag: payload })
+                const { result } = renderHook(() => useFeatureFlagResult('my_flag'), { wrapper })
+                expect(result.current).toEqual({
+                    key: 'my_flag',
+                    enabled: true,
+                    variant: undefined,
+                    payload,
+                })
+            })
+
+            it('returns undefined for a missing flag', () => {
+                const wrapper = renderWithBootstrap({ other_flag: true })
+                const { result } = renderHook(() => useFeatureFlagResult('my_flag'), { wrapper })
+                expect(result.current).toBeUndefined()
+            })
+        })
+
+        describe('flag updates', () => {
+            it('re-renders when onFeatureFlags fires', () => {
+                let capturedCallback: (() => void) | undefined
+                const client = {
+                    getFeatureFlagResult: jest.fn().mockReturnValue({
+                        key: 'flag',
+                        enabled: true,
+                        variant: undefined,
+                        payload: undefined,
+                    }),
+                    onFeatureFlags: (cb: () => void) => {
+                        capturedCallback = cb
+                        return () => {}
+                    },
+                    featureFlags: {
+                        hasLoadedFlags: true,
+                    } as unknown as PostHog['featureFlags'],
+                } as unknown as PostHog
+
+                // eslint-disable-next-line react/display-name
+                const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+                    <PostHogProvider client={client}>{children}</PostHogProvider>
+                )
+
+                const { result } = renderHook(() => useFeatureFlagResult('flag'), { wrapper })
+                expect(result.current).toEqual({
+                    key: 'flag',
+                    enabled: true,
+                    variant: undefined,
+                    payload: undefined,
+                })
+                ;(client.getFeatureFlagResult as jest.Mock).mockReturnValue({
+                    key: 'flag',
+                    enabled: true,
+                    variant: 'new-variant',
+                    payload: undefined,
+                })
+
+                act(() => {
+                    capturedCallback!()
+                })
+
+                expect(result.current).toEqual({
+                    key: 'flag',
+                    enabled: true,
+                    variant: 'new-variant',
+                    payload: undefined,
+                })
+            })
+        })
+
+        describe('cleanup', () => {
+            it('unsubscribes from onFeatureFlags on unmount', () => {
+                const unsubscribe = jest.fn()
+                const client = {
+                    getFeatureFlagResult: () => undefined,
+                    onFeatureFlags: () => unsubscribe,
+                    featureFlags: {
+                        hasLoadedFlags: true,
+                    } as unknown as PostHog['featureFlags'],
+                } as unknown as PostHog
+
+                // eslint-disable-next-line react/display-name
+                const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+                    <PostHogProvider client={client}>{children}</PostHogProvider>
+                )
+
+                const { unmount } = renderHook(() => useFeatureFlagResult('flag'), { wrapper })
+                expect(unsubscribe).not.toHaveBeenCalled()
+
+                unmount()
+                expect(unsubscribe).toHaveBeenCalledTimes(1)
+            })
+        })
+    })
+})

package/src/hooks/__tests__/usePostHog.test.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react'
+import { renderHook } from '@testing-library/react'
+import { PostHogProvider, PostHog } from '../../context'
+import { usePostHog } from '..'
+
+jest.useFakeTimers()
+
+const posthog = { posthog_client: true } as unknown as PostHog
+
+describe('usePostHog hook', () => {
+    it('should return the client', () => {
+        const { result } = renderHook(() => usePostHog(), {
+            wrapper: ({ children }: { children: React.ReactNode }) => (
+                <PostHogProvider client={posthog}>{children}</PostHogProvider>
+            ),
+        })
+        expect(result.current).toEqual(posthog)
+    })
+})

package/src/hooks/__tests__/useThumbSurvey.test.tsx

@@ -0,0 +1,105 @@
+import * as React from 'react'
+import { renderHook, act } from '@testing-library/react'
+import { PostHogProvider, PostHog } from '../../context'
+import { useThumbSurvey } from '../useThumbSurvey'
+import { SurveyEventName, SurveyEventProperties } from '@hanzo/insights'
+import { isUndefined } from '../../utils/type-utils'
+
+jest.useFakeTimers()
+
+describe('useThumbSurvey hook', () => {
+    let posthog: PostHog
+    let captureMock: jest.Mock
+    let displaySurveyMock: jest.Mock
+    let wrapper: React.FC<{ children: React.ReactNode }>
+
+    beforeEach(() => {
+        captureMock = jest.fn()
+        displaySurveyMock = jest.fn()
+
+        posthog = {
+            capture: captureMock,
+            get_session_replay_url: () => 'https://app.posthog.com/replay/123',
+            surveys: { displaySurvey: displaySurveyMock },
+        } as unknown as PostHog
+
+        wrapper = ({ children }) => <PostHogProvider client={posthog}>{children}</PostHogProvider>
+    })
+
+    describe('survey shown tracking', () => {
+        it.each([
+            [false, true, false], // disableAutoShownTracking, shouldAutoTrack, shouldExposeTrackShown
+            [true, false, true],
+        ])(
+            'disableAutoShownTracking=%s: auto-tracks=%s, exposes trackShown=%s',
+            (disableAutoShownTracking, shouldAutoTrack, shouldExposeTrackShown) => {
+                const { result } = renderHook(
+                    () => useThumbSurvey({ surveyId: 'test-survey', disableAutoShownTracking }),
+                    { wrapper }
+                )
+
+                expect(captureMock).toHaveBeenCalledTimes(shouldAutoTrack ? 1 : 0)
+                expect(!isUndefined(result.current.trackShown)).toBe(shouldExposeTrackShown)
+            }
+        )
+
+        it('should only emit survey shown once when trackShown is called multiple times', () => {
+            const { result } = renderHook(
+                () => useThumbSurvey({ surveyId: 'test-survey', disableAutoShownTracking: true }),
+                { wrapper }
+            )
+
+            act(() => {
+                result.current.trackShown?.()
+                result.current.trackShown?.()
+            })
+
+            expect(captureMock).toHaveBeenCalledTimes(1)
+            expect(captureMock).toHaveBeenCalledWith(SurveyEventName.SHOWN, {
+                [SurveyEventProperties.SURVEY_ID]: 'test-survey',
+                sessionRecordingUrl: 'https://app.posthog.com/replay/123',
+            })
+        })
+    })
+
+    describe('respond', () => {
+        it.each([
+            ['up', 1],
+            ['down', 2],
+        ] as const)('respond("%s") calls displaySurvey with initialResponses: { 0: %d }', (value, expectedResponse) => {
+            const { result } = renderHook(() => useThumbSurvey({ surveyId: 'test-survey' }), { wrapper })
+
+            act(() => {
+                result.current.respond(value)
+            })
+
+            expect(displaySurveyMock).toHaveBeenCalledWith(
+                'test-survey',
+                expect.objectContaining({ initialResponses: { 0: expectedResponse } })
+            )
+        })
+
+        it('should only allow one response', () => {
+            const { result } = renderHook(() => useThumbSurvey({ surveyId: 'test-survey' }), { wrapper })
+
+            act(() => {
+                result.current.respond('up')
+                result.current.respond('down')
+            })
+
+            expect(displaySurveyMock).toHaveBeenCalledTimes(1)
+            expect(result.current.response).toBe('up')
+        })
+
+        it('should call onResponse callback', () => {
+            const onResponse = jest.fn()
+            const { result } = renderHook(() => useThumbSurvey({ surveyId: 'test-survey', onResponse }), { wrapper })
+
+            act(() => {
+                result.current.respond('down')
+            })
+
+            expect(onResponse).toHaveBeenCalledWith('down')
+        })
+    })
+})

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+export * from './useFeatureFlagEnabled'
+export * from './useFeatureFlagPayload'
+export * from './useFeatureFlagResult'
+export * from './useActiveFeatureFlags'
+export * from './useFeatureFlagVariantKey'
+export * from './usePostHog'

package/src/hooks/useActiveFeatureFlags.ts

@@ -0,0 +1,21 @@
+import { useContext, useEffect, useState } from 'react'
+import { PostHogContext } from '../context'
+
+export function useActiveFeatureFlags(): string[] {
+    const { client, bootstrap } = useContext(PostHogContext)
+
+    const [featureFlags, setFeatureFlags] = useState<string[]>(() => client.featureFlags.getFlags())
+
+    useEffect(() => {
+        return client.onFeatureFlags((flags) => {
+            setFeatureFlags(flags)
+        })
+    }, [client])
+
+    // if the client is not loaded yet and we have a bootstrapped value, use it
+    if (!client?.featureFlags?.hasLoadedFlags && bootstrap?.featureFlags) {
+        return Object.keys(bootstrap.featureFlags)
+    }
+
+    return featureFlags
+}

package/src/hooks/useFeatureFlagEnabled.ts

@@ -0,0 +1,24 @@
+import { useContext, useEffect, useState } from 'react'
+import { PostHogContext } from '../context'
+import { isUndefined } from '../utils/type-utils'
+
+export function useFeatureFlagEnabled(flag: string): boolean | undefined {
+    const { client, bootstrap } = useContext(PostHogContext)
+
+    const [featureEnabled, setFeatureEnabled] = useState<boolean | undefined>(() => client.isFeatureEnabled(flag))
+
+    useEffect(() => {
+        return client.onFeatureFlags(() => {
+            setFeatureEnabled(client.isFeatureEnabled(flag))
+        })
+    }, [client, flag])
+
+    const bootstrapped = bootstrap?.featureFlags?.[flag]
+
+    // if the client is not loaded yet, check if we have a bootstrapped value and then true/false it
+    if (!client?.featureFlags?.hasLoadedFlags && bootstrap?.featureFlags) {
+        return isUndefined(bootstrapped) ? undefined : !!bootstrapped
+    }
+
+    return featureEnabled
+}

package/src/hooks/useFeatureFlagPayload.ts

@@ -0,0 +1,22 @@
+import { JsonType } from '@hanzo/insights'
+import { useContext, useEffect, useState } from 'react'
+import { PostHogContext } from '../context'
+
+export function useFeatureFlagPayload(flag: string): JsonType {
+    const { client, bootstrap } = useContext(PostHogContext)
+
+    const [featureFlagPayload, setFeatureFlagPayload] = useState<JsonType>(() => client.getFeatureFlagPayload(flag))
+
+    useEffect(() => {
+        return client.onFeatureFlags(() => {
+            setFeatureFlagPayload(client.getFeatureFlagPayload(flag))
+        })
+    }, [client, flag])
+
+    // if the client is not loaded yet, use the bootstrapped value
+    if (!client?.featureFlags?.hasLoadedFlags && bootstrap?.featureFlagPayloads) {
+        return bootstrap.featureFlagPayloads[flag]
+    }
+
+    return featureFlagPayload
+}

package/src/hooks/useFeatureFlagResult.ts

@@ -0,0 +1,31 @@
+import { FeatureFlagResult } from '@hanzo/insights'
+import { useContext, useEffect, useState } from 'react'
+import { PostHogContext } from '../context'
+import { isUndefined } from '../utils/type-utils'
+
+export function useFeatureFlagResult(flag: string): FeatureFlagResult | undefined {
+    const { client, bootstrap } = useContext(PostHogContext)
+
+    const [result, setResult] = useState<FeatureFlagResult | undefined>(() => client.getFeatureFlagResult(flag))
+
+    useEffect(() => {
+        return client.onFeatureFlags(() => {
+            setResult(client.getFeatureFlagResult(flag))
+        })
+    }, [client, flag])
+
+    if (!client?.featureFlags?.hasLoadedFlags && bootstrap?.featureFlags) {
+        const bootstrappedValue = bootstrap.featureFlags[flag]
+        if (isUndefined(bootstrappedValue)) {
+            return undefined
+        }
+        return {
+            key: flag,
+            enabled: typeof bootstrappedValue === 'string' ? true : !!bootstrappedValue,
+            variant: typeof bootstrappedValue === 'string' ? bootstrappedValue : undefined,
+            payload: bootstrap.featureFlagPayloads?.[flag],
+        }
+    }
+
+    return result
+}