@hubspot/ui-extensions 0.9.2 → 0.9.4

package/dist/__tests__/experimental/hooks/useAssociations.spec.js

@@ -0,0 +1,368 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { useAssociations } from '../../../experimental/hooks/useAssociations';
+// Mock the logger module
+jest.mock('../../../logger', () => ({
+    logger: {
+        debug: jest.fn(),
+        info: jest.fn(),
+        warn: jest.fn(),
+        error: jest.fn(),
+    },
+}));
+// Mock the fetchAssociations module
+jest.mock('../../../experimental/crm/fetchAssociations');
+const mockFetchAssociations = jest.fn();
+import * as fetchAssociationsModule from '../../../experimental/crm/fetchAssociations';
+fetchAssociationsModule.fetchAssociations = mockFetchAssociations;
+describe('useAssociations', () => {
+    let originalError;
+    beforeAll(() => {
+        // Suppress React act() warning coming from @testing-library/react
+        originalError = console.error;
+        console.error = (...args) => {
+            if (args[0]?.includes('ReactDOMTestUtils.act'))
+                return;
+            originalError.call(console, ...args);
+        };
+    });
+    beforeEach(() => {
+        // Reset the mock before each test
+        mockFetchAssociations.mockReset();
+    });
+    afterAll(() => {
+        console.error = originalError;
+    });
+    describe('initial state', () => {
+        it('should return the initial values for results, error, isLoading, hasMore, and nextOffset', async () => {
+            const { result } = renderHook(() => useAssociations({
+                toObjectType: '0-1',
+                properties: ['firstname', 'lastname'],
+                pageLength: 25,
+                offset: 0,
+            }));
+            await waitFor(() => {
+                expect(result.current.results).toEqual([]);
+                expect(result.current.error).toBeNull();
+                expect(result.current.isLoading).toBe(true);
+                expect(result.current.hasMore).toBe(false);
+                expect(result.current.nextOffset).toBe(0);
+            });
+        });
+    });
+    describe('successful data fetching', () => {
+        it('should successfully fetch and return associations', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [
+                        {
+                            toObjectId: 1001,
+                            associationTypes: [
+                                { category: 'HUBSPOT_DEFINED', typeId: 1, label: 'Primary' },
+                            ],
+                            properties: {
+                                firstname: 'John',
+                                lastname: 'Doe',
+                            },
+                        },
+                        {
+                            toObjectId: 1002,
+                            associationTypes: [
+                                { category: 'USER_DEFINED', typeId: 100, label: 'Custom' },
+                            ],
+                            properties: {
+                                firstname: 'Jane',
+                                lastname: 'Smith',
+                            },
+                        },
+                    ],
+                    hasMore: true,
+                    nextOffset: 25,
+                },
+                cleanup: jest.fn(),
+            });
+            const request = {
+                toObjectType: '0-1',
+                properties: ['firstname', 'lastname'],
+                pageLength: 25,
+                offset: 0,
+            };
+            const { result } = renderHook(() => useAssociations(request));
+            await waitFor(() => {
+                expect(result.current.results).toEqual([
+                    {
+                        toObjectId: 1001,
+                        associationTypes: [
+                            { category: 'HUBSPOT_DEFINED', typeId: 1, label: 'Primary' },
+                        ],
+                        properties: {
+                            firstname: 'John',
+                            lastname: 'Doe',
+                        },
+                    },
+                    {
+                        toObjectId: 1002,
+                        associationTypes: [
+                            { category: 'USER_DEFINED', typeId: 100, label: 'Custom' },
+                        ],
+                        properties: {
+                            firstname: 'Jane',
+                            lastname: 'Smith',
+                        },
+                    },
+                ]);
+                expect(result.current.error).toBeNull();
+                expect(result.current.isLoading).toBe(false);
+                expect(result.current.hasMore).toBe(true);
+                expect(result.current.nextOffset).toBe(25);
+            });
+        });
+        it('should handle empty results correctly', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const request = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 25,
+                offset: 0,
+            };
+            const { result } = renderHook(() => useAssociations(request));
+            await waitFor(() => {
+                expect(result.current.results).toEqual([]);
+                expect(result.current.hasMore).toBe(false);
+                expect(result.current.nextOffset).toBe(0);
+                expect(result.current.isLoading).toBe(false);
+                expect(result.current.error).toBeNull();
+            });
+        });
+        it('should handle different object types correctly', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [
+                        {
+                            toObjectId: 2001,
+                            associationTypes: [
+                                {
+                                    category: 'HUBSPOT_DEFINED',
+                                    typeId: 2,
+                                    label: 'Company Primary',
+                                },
+                            ],
+                            properties: {
+                                name: 'Test Company',
+                            },
+                        },
+                    ],
+                    hasMore: false,
+                    nextOffset: 25,
+                },
+                cleanup: jest.fn(),
+            });
+            const request = {
+                toObjectType: '0-2',
+                properties: ['name'],
+                pageLength: 25,
+                offset: 0,
+            };
+            const { result } = renderHook(() => useAssociations(request));
+            await waitFor(() => {
+                expect(result.current.results).toEqual([
+                    {
+                        toObjectId: 2001,
+                        associationTypes: [
+                            {
+                                category: 'HUBSPOT_DEFINED',
+                                typeId: 2,
+                                label: 'Company Primary',
+                            },
+                        ],
+                        properties: {
+                            name: 'Test Company',
+                        },
+                    },
+                ]);
+                expect(result.current.isLoading).toBe(false);
+            });
+            expect(mockFetchAssociations).toHaveBeenCalledWith(expect.objectContaining({
+                toObjectType: '0-2',
+            }), {});
+        });
+    });
+    describe('error handling', () => {
+        it('should handle fetch errors correctly', async () => {
+            const errorMessage = 'Failed to fetch associations';
+            mockFetchAssociations.mockRejectedValue(new Error(errorMessage));
+            const request = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 25,
+                offset: 0,
+            };
+            const { result } = renderHook(() => useAssociations(request));
+            await waitFor(() => {
+                expect(result.current.error).toBeInstanceOf(Error);
+                expect(result.current.error?.message).toBe(errorMessage);
+                expect(result.current.results).toEqual([]);
+                expect(result.current.isLoading).toBe(false);
+                expect(result.current.hasMore).toBe(false);
+                expect(result.current.nextOffset).toBe(0);
+            });
+        });
+    });
+    describe('pagination handling', () => {
+        it('should handle pagination correctly', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [
+                        {
+                            toObjectId: 1025,
+                            associationTypes: [
+                                { category: 'HUBSPOT_DEFINED', typeId: 1, label: 'Primary' },
+                            ],
+                            properties: {
+                                firstname: 'Page 2 User',
+                            },
+                        },
+                    ],
+                    hasMore: false,
+                    nextOffset: 50,
+                },
+                cleanup: jest.fn(),
+            });
+            const request = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 25,
+                offset: 25, // Second page
+            };
+            const { result } = renderHook(() => useAssociations(request));
+            await waitFor(() => {
+                expect(result.current.results).toEqual([
+                    {
+                        toObjectId: 1025,
+                        associationTypes: [
+                            { category: 'HUBSPOT_DEFINED', typeId: 1, label: 'Primary' },
+                        ],
+                        properties: {
+                            firstname: 'Page 2 User',
+                        },
+                    },
+                ]);
+                expect(result.current.hasMore).toBe(false);
+                expect(result.current.nextOffset).toBe(50);
+                expect(result.current.isLoading).toBe(false);
+            });
+        });
+    });
+    describe('options handling', () => {
+        it('should pass formatting options to fetchAssociations', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const request = {
+                toObjectType: '0-1',
+                properties: ['firstname', 'lastname'],
+                pageLength: 25,
+                offset: 0,
+            };
+            const options = {
+                propertiesToFormat: ['firstname'],
+                formattingOptions: {
+                    date: {
+                        format: 'MM/DD/YYYY',
+                        relative: true,
+                    },
+                },
+            };
+            renderHook(() => useAssociations(request, options));
+            await waitFor(() => {
+                expect(mockFetchAssociations).toHaveBeenCalledWith(request, options);
+            });
+        });
+        it('should use default empty options when no options provided', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const request = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 25,
+                offset: 0,
+            };
+            renderHook(() => useAssociations(request));
+            await waitFor(() => {
+                expect(mockFetchAssociations).toHaveBeenCalledWith(request, {});
+            });
+        });
+    });
+    describe('lifecycle management', () => {
+        it('should call cleanup function on unmount', async () => {
+            const mockCleanup = jest.fn();
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: mockCleanup,
+            });
+            const request = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 25,
+                offset: 0,
+            };
+            const { unmount } = renderHook(() => useAssociations(request));
+            await waitFor(() => {
+                expect(mockFetchAssociations).toHaveBeenCalled();
+            });
+            unmount();
+            await waitFor(() => {
+                expect(mockCleanup).toHaveBeenCalled();
+            });
+        });
+        it('should handle stable reference optimization for request', async () => {
+            mockFetchAssociations.mockResolvedValue({
+                data: {
+                    results: [],
+                    hasMore: false,
+                    nextOffset: 0,
+                },
+                cleanup: jest.fn(),
+            });
+            const request = {
+                toObjectType: '0-1',
+                properties: ['firstname'],
+                pageLength: 25,
+                offset: 0,
+            };
+            const { rerender } = renderHook(({ requestProp }) => useAssociations(requestProp), {
+                initialProps: { requestProp: request },
+            });
+            await waitFor(() => {
+                expect(mockFetchAssociations).toHaveBeenCalledTimes(1);
+            });
+            // Rerender with the same request object content but different reference
+            rerender({ requestProp: { ...request } });
+            await waitFor(() => {
+                // Should not call fetchAssociations again due to stable reference optimization
+                expect(mockFetchAssociations).toHaveBeenCalledTimes(1);
+            });
+        });
+    });
+});

package/dist/__tests__/experimental/hooks/useCrmProperties.spec.js

@@ -42,8 +42,11 @@ describe('useCrmProperties', () => {
     });
     it('should successfully fetch and return CRM properties', async () => {
         mockFetchCrmProperties.mockResolvedValue({
-            firstname: 'Test value for firstname',
-            lastname: 'Test value for lastname',
+            data: {
+                firstname: 'Test value for firstname',
+                lastname: 'Test value for lastname',
+            },
+            cleanup: jest.fn(),
         });
         const propertyNames = ['firstname', 'lastname'];
         const { result } = renderHook(() => useCrmProperties(propertyNames));
@@ -73,7 +76,10 @@ describe('useCrmProperties', () => {
         let capturedCallback;
         mockFetchCrmProperties.mockImplementation((_propertyNames, propertiesUpdatedCallback) => {
             capturedCallback = propertiesUpdatedCallback;
-            return { firstname: 'Initial', lastname: 'Initial' };
+            return {
+                data: { firstname: 'Initial', lastname: 'Initial' },
+                cleanup: jest.fn(),
+            };
         });
         const propertyNames = ['firstname', 'lastname'];
         const { result } = renderHook(() => useCrmProperties(propertyNames));
@@ -87,9 +93,150 @@ describe('useCrmProperties', () => {
         const updatedProperties = { firstname: 'Updated', lastname: 'Updated' };
         await waitFor(() => {
             if (capturedCallback) {
-                capturedCallback(updatedProperties);
+                capturedCallback?.(updatedProperties);
+                expect(result.current.properties).toEqual(updatedProperties);
+            }
+        });
+    });
+    it('should update properties when propertiesUpdatedCallback is called with null values', async () => {
+        // Capture the callback so we can simulate an external update to CRM properties
+        let capturedCallback;
+        mockFetchCrmProperties.mockImplementation((_propertyNames, propertiesUpdatedCallback) => {
+            capturedCallback = propertiesUpdatedCallback;
+            return {
+                data: { firstname: 'Initial', lastname: null },
+                cleanup: jest.fn(),
+            };
+        });
+        const propertyNames = ['firstname', 'lastname'];
+        const { result } = renderHook(() => useCrmProperties(propertyNames));
+        await waitFor(() => {
+            expect(result.current.properties).toEqual({
+                firstname: 'Initial',
+                lastname: null,
+            });
+            expect(result.current.isLoading).toBe(false);
+        });
+        const updatedProperties = { firstname: null, lastname: 'Updated Value' };
+        await waitFor(() => {
+            if (capturedCallback) {
+                capturedCallback?.(updatedProperties);
                 expect(result.current.properties).toEqual(updatedProperties);
             }
         });
     });
+    // This will become "should pass formatting options to fetchCrmProperties" in the next PR
+    it('should pass formatting options to fetchCrmProperties', async () => {
+        mockFetchCrmProperties.mockResolvedValue({
+            data: {
+                firstname: 'John',
+                lastname: 'Doe',
+            },
+            cleanup: jest.fn(),
+        });
+        const propertyNames = ['firstname', 'lastname'];
+        const options = {
+            propertiesToFormat: ['firstname'],
+        };
+        renderHook(() => useCrmProperties(propertyNames, options));
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledWith(propertyNames, expect.any(Function), options);
+        });
+    });
+    it('should use default empty options when no options provided', async () => {
+        mockFetchCrmProperties.mockResolvedValue({
+            data: {
+                firstname: 'John',
+            },
+            cleanup: jest.fn(),
+        });
+        const propertyNames = ['firstname'];
+        const defaultOptions = {};
+        renderHook(() => useCrmProperties(propertyNames));
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledWith(['firstname'], expect.any(Function), defaultOptions);
+        });
+    });
+    it('should not re-fetch when options object reference changes but content is the same', async () => {
+        mockFetchCrmProperties.mockResolvedValue({
+            data: {
+                firstname: 'John',
+            },
+            cleanup: jest.fn(),
+        });
+        const propertyNames = ['firstname'];
+        const initialOptions = { propertiesToFormat: ['firstname'] };
+        const { rerender } = renderHook(({ options }) => useCrmProperties(propertyNames, options), { initialProps: { options: initialOptions } });
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledTimes(1);
+        });
+        const newOptionsWithSameContent = { propertiesToFormat: ['firstname'] };
+        rerender({ options: newOptionsWithSameContent });
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledTimes(1);
+        });
+    });
+    it('should re-fetch when options content actually changes', async () => {
+        mockFetchCrmProperties.mockResolvedValue({
+            data: {
+                firstname: 'John',
+            },
+            cleanup: jest.fn(),
+        });
+        const propertyNames = ['firstname'];
+        const initialOptions = { propertiesToFormat: ['firstname'] };
+        const { rerender } = renderHook(({ options }) => useCrmProperties(propertyNames, options), { initialProps: { options: initialOptions } });
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledTimes(1);
+            expect(mockFetchCrmProperties).toHaveBeenLastCalledWith(['firstname'], expect.any(Function), initialOptions);
+        });
+        const newOptions = {
+            propertiesToFormat: ['firstname'],
+            formattingOptions: { dateFormat: 'yyyy-MM-dd' },
+        };
+        rerender({ options: newOptions });
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledTimes(2);
+            expect(mockFetchCrmProperties).toHaveBeenLastCalledWith(['firstname'], expect.any(Function), newOptions);
+        });
+    });
+    it('should call cleanup function when component unmounts', async () => {
+        const mockCleanup = jest.fn();
+        mockFetchCrmProperties.mockResolvedValue({
+            data: {
+                firstname: 'John',
+            },
+            cleanup: mockCleanup,
+        });
+        const propertyNames = ['firstname'];
+        const { unmount } = renderHook(() => useCrmProperties(propertyNames));
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledTimes(1);
+        });
+        unmount();
+        expect(mockCleanup).toHaveBeenCalledTimes(1);
+    });
+    it('should call cleanup function when dependencies change', async () => {
+        const mockCleanup1 = jest.fn();
+        const mockCleanup2 = jest.fn();
+        mockFetchCrmProperties
+            .mockResolvedValueOnce({
+            data: { firstname: 'John' },
+            cleanup: mockCleanup1,
+        })
+            .mockResolvedValueOnce({
+            data: { firstname: 'Jane' },
+            cleanup: mockCleanup2,
+        });
+        const { rerender } = renderHook(({ propertyNames }) => useCrmProperties(propertyNames), { initialProps: { propertyNames: ['firstname'] } });
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledTimes(1);
+        });
+        // Change dependencies to trigger cleanup
+        rerender({ propertyNames: ['lastname'] });
+        await waitFor(() => {
+            expect(mockFetchCrmProperties).toHaveBeenCalledTimes(2);
+            expect(mockCleanup1).toHaveBeenCalledTimes(1);
+        });
+    });
 });

package/dist/experimental/crm/fetchAssociations.d.ts

@@ -0,0 +1,29 @@
+import { FetchCrmPropertiesOptions } from './fetchCrmProperties';
+export type AssociationResult = {
+    toObjectId: number;
+    associationTypes: {
+        category: string;
+        typeId: number;
+        label: string;
+    }[];
+    properties: {
+        [key: string]: string | null;
+    };
+};
+export type AssociationsResponse = {
+    results: AssociationResult[];
+    hasMore: boolean;
+    nextOffset: number;
+};
+export type FetchAssociationsRequest = {
+    toObjectType: string;
+    properties?: string[];
+    pageLength?: number;
+    offset?: number;
+};
+export interface FetchAssociationsResult {
+    data: AssociationsResponse;
+    error?: string;
+    cleanup: () => void;
+}
+export declare const fetchAssociations: (request: FetchAssociationsRequest, options?: FetchCrmPropertiesOptions) => Promise<FetchAssociationsResult>;

package/dist/experimental/crm/fetchAssociations.js

@@ -0,0 +1,42 @@
+function isAssociationsResponse(data) {
+    if (data === null ||
+        typeof data !== 'object' ||
+        !Array.isArray(data.results) ||
+        typeof data.hasMore !== 'boolean' ||
+        typeof data.nextOffset !== 'number') {
+        return false;
+    }
+    return data.results.every((result) => result !== null &&
+        typeof result === 'object' &&
+        typeof result.toObjectId === 'number' &&
+        Array.isArray(result.associationTypes) &&
+        result.properties !== null &&
+        typeof result.properties === 'object');
+}
+export const fetchAssociations = async (request, options) => {
+    let response;
+    let result;
+    try {
+        // eslint-disable-next-line hubspot-dev/no-confusing-browser-globals
+        response = await self.fetchAssociations(request, options);
+        result = await response.json();
+    }
+    catch (error) {
+        throw error instanceof Error
+            ? error
+            : new Error('Failed to fetch associations: Unknown error');
+    }
+    if (result.error) {
+        throw new Error(result.error);
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch associations: ${response.statusText}`);
+    }
+    if (!isAssociationsResponse(result.data)) {
+        throw new Error('Invalid response format');
+    }
+    return {
+        data: result.data,
+        cleanup: result.cleanup || (() => { }),
+    };
+};

package/dist/experimental/crm/fetchCrmProperties.d.ts

@@ -1,4 +1,25 @@
 export type CrmPropertiesResponse = {
-    [key: string]: string;
+    [key: string]: string | null;
 };
-export declare const fetchCrmProperties: (propertyNames: string[], propertiesUpdatedCallback: (properties: Record<string, string>) => void) => Promise<Record<string, string>>;
+export type FetchCrmPropertiesOptions = {
+    propertiesToFormat?: string[] | 'all';
+    formattingOptions?: {
+        date?: {
+            format?: string;
+            relative?: boolean;
+        };
+        dateTime?: {
+            format?: string;
+            relative?: boolean;
+        };
+        currency?: {
+            addSymbol?: boolean;
+        };
+    };
+};
+export interface FetchCrmPropertiesResult {
+    data: Record<string, string | null>;
+    error?: string;
+    cleanup: () => void;
+}
+export declare const fetchCrmProperties: (propertyNames: string[], propertiesUpdatedCallback: (properties: Record<string, string | null>) => void, options?: FetchCrmPropertiesOptions) => Promise<FetchCrmPropertiesResult>;