@hubspot/ui-extensions 0.9.3 → 0.9.4

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

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/experimental/crm/fetchAssociations.spec.js

@@ -0,0 +1,396 @@
+// Set up the mock before importing the module
+const mockFetchAssociations = jest.fn();
+const mockSelf = {
+    fetchAssociations: mockFetchAssociations,
+};
+// Mock the global self object
+Object.defineProperty(global, 'self', {
+    value: mockSelf,
+    writable: true,
+});
+import { fetchAssociations } from '../../../experimental/crm/fetchAssociations';
+describe('fetchAssociations', () => {
+    // Helper functions
+    const createMockResponse = (data, overrides = {}) => ({
+        ok: true,
+        json: jest.fn().mockResolvedValue({ data, cleanup: jest.fn() }),
+        ...overrides,
+    });
+    const createErrorResponse = (statusText) => ({
+        ok: false,
+        statusText,
+        json: jest.fn().mockResolvedValue({}),
+    });
+    const expectError = async (request, expectedMessage) => {
+        await expect(fetchAssociations(request)).rejects.toThrow(expectedMessage);
+    };
+    const createBasicRequest = (overrides = {}) => ({
+        toObjectType: '0-1',
+        properties: ['firstname', 'lastname'],
+        ...overrides,
+    });
+    beforeEach(() => {
+        jest.clearAllMocks();
+        // Set up dynamic mock that responds to request parameters
+        mockFetchAssociations.mockImplementation((request) => {
+            const { pageLength = 100, offset = 0, properties = [] } = request;
+            // Generate mock properties based on the request
+            const mockProperties = {};
+            properties.forEach((prop) => {
+                mockProperties[prop] = `Mock ${prop} (page ${Math.floor(offset / pageLength) + 1})`;
+            });
+            const mockResults = [
+                {
+                    toObjectId: 1000 + offset,
+                    associationTypes: [
+                        { category: 'HUBSPOT_DEFINED', typeId: 1, label: 'Primary' },
+                    ],
+                    properties: mockProperties,
+                },
+                {
+                    toObjectId: 1001 + offset,
+                    associationTypes: [
+                        {
+                            category: 'USER_DEFINED',
+                            typeId: 100,
+                            label: 'Custom Association',
+                        },
+                    ],
+                    properties: mockProperties,
+                },
+            ];
+            const mockData = {
+                results: mockResults,
+                hasMore: offset < 200,
+                nextOffset: offset + pageLength,
+            };
+            return Promise.resolve(createMockResponse(mockData));
+        });
+    });
+    describe('basic functionality', () => {
+        it('should return mock associations with default parameters', async () => {
+            const request = createBasicRequest();
+            const result = await fetchAssociations(request);
+            expect(result).toHaveProperty('data');
+            expect(result).toHaveProperty('cleanup');
+            expect(typeof result.cleanup).toBe('function');
+            const { data } = result;
+            expect(data.results).toHaveLength(2);
+            expect(data.hasMore).toBe(true);
+            expect(data.nextOffset).toBe(100);
+            // Check first association
+            expect(data.results[0]).toEqual({
+                toObjectId: 1000,
+                associationTypes: [
+                    { category: 'HUBSPOT_DEFINED', typeId: 1, label: 'Primary' },
+                ],
+                properties: {
+                    firstname: 'Mock firstname (page 1)',
+                    lastname: 'Mock lastname (page 1)',
+                },
+            });
+            // Check second association
+            expect(data.results[1]).toEqual({
+                toObjectId: 1001,
+                associationTypes: [
+                    {
+                        category: 'USER_DEFINED',
+                        typeId: 100,
+                        label: 'Custom Association',
+                    },
+                ],
+                properties: {
+                    firstname: 'Mock firstname (page 1)',
+                    lastname: 'Mock lastname (page 1)',
+                },
+            });
+        });
+        it('should return a cleanup function', async () => {
+            const request = createBasicRequest({ properties: ['firstname'] });
+            const result = await fetchAssociations(request);
+            expect(typeof result.cleanup).toBe('function');
+            // Should not throw when called
+            expect(() => result.cleanup()).not.toThrow();
+        });
+        it('should return a Promise', () => {
+            const request = createBasicRequest({ properties: ['firstname'] });
+            const result = fetchAssociations(request);
+            expect(result).toBeInstanceOf(Promise);
+        });
+    });
+    describe('pagination handling', () => {
+        it('should handle custom page length and offset', async () => {
+            const request = createBasicRequest({
+                properties: ['email'],
+                pageLength: 25,
+                offset: 50,
+            });
+            const result = await fetchAssociations(request);
+            const { data } = result;
+            expect(data.results).toHaveLength(2);
+            expect(data.nextOffset).toBe(75); // 50 + 25
+            expect(data.hasMore).toBe(true);
+            // Check that offset is reflected in object IDs
+            expect(data.results[0].toObjectId).toBe(1050); // 1000 + 50
+            expect(data.results[1].toObjectId).toBe(1051); // 1001 + 50
+            // Check that page number is reflected in properties
+            expect(data.results[0].properties.email).toBe('Mock email (page 3)'); // Math.floor(50 / 25) + 1 = 3
+        });
+        it('should calculate hasMore correctly based on offset', async () => {
+            // Test when there are more results
+            const request1 = createBasicRequest({
+                properties: ['firstname'],
+                offset: 100,
+            });
+            const result1 = await fetchAssociations(request1);
+            expect(result1.data.hasMore).toBe(true);
+            // Test when there are no more results
+            const request2 = createBasicRequest({
+                properties: ['firstname'],
+                offset: 200,
+            });
+            const result2 = await fetchAssociations(request2);
+            expect(result2.data.hasMore).toBe(false);
+            // Test edge case at the boundary
+            const request3 = createBasicRequest({
+                properties: ['firstname'],
+                offset: 199,
+            });
+            const result3 = await fetchAssociations(request3);
+            expect(result3.data.hasMore).toBe(true);
+        });
+        it('should generate different page numbers for different offsets', async () => {
+            const request1 = createBasicRequest({
+                properties: ['firstname'],
+                pageLength: 10,
+                offset: 0,
+            });
+            const result1 = await fetchAssociations(request1);
+            expect(result1.data.results[0].properties.firstname).toBe('Mock firstname (page 1)');
+            const request2 = createBasicRequest({
+                properties: ['firstname'],
+                pageLength: 10,
+                offset: 20,
+            });
+            const result2 = await fetchAssociations(request2);
+            expect(result2.data.results[0].properties.firstname).toBe('Mock firstname (page 3)'); // Math.floor(20 / 10) + 1 = 3
+        });
+    });
+    describe('properties handling', () => {
+        it('should handle empty properties array', async () => {
+            const request = createBasicRequest({ properties: [] });
+            const result = await fetchAssociations(request);
+            const { data } = result;
+            expect(data.results).toHaveLength(2);
+            expect(data.results[0].properties).toEqual({});
+            expect(data.results[1].properties).toEqual({});
+        });
+        it('should handle missing properties in request', async () => {
+            const request = createBasicRequest();
+            // Remove properties to test missing case
+            delete request.properties;
+            const result = await fetchAssociations(request);
+            const { data } = result;
+            expect(data.results).toHaveLength(2);
+            expect(data.results[0].properties).toEqual({});
+            expect(data.results[1].properties).toEqual({});
+        });
+        it('should handle multiple properties correctly', async () => {
+            const request = createBasicRequest({
+                properties: ['firstname', 'lastname', 'email', 'phone'],
+            });
+            const result = await fetchAssociations(request);
+            const { data } = result;
+            expect(data.results[0].properties).toEqual({
+                firstname: 'Mock firstname (page 1)',
+                lastname: 'Mock lastname (page 1)',
+                email: 'Mock email (page 1)',
+                phone: 'Mock phone (page 1)',
+            });
+        });
+        it('should handle different object types', async () => {
+            const request = createBasicRequest({
+                toObjectType: '0-2',
+                properties: ['name'],
+            });
+            const result = await fetchAssociations(request);
+            const { data } = result;
+            expect(data.results).toHaveLength(2);
+            expect(data.results[0].properties.name).toBe('Mock name (page 1)');
+        });
+    });
+    describe('error handling', () => {
+        it('should throw an error when response is not OK', async () => {
+            mockFetchAssociations.mockResolvedValueOnce(createErrorResponse('Not Found'));
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expectError(request, 'Failed to fetch associations: Not Found');
+        });
+        it('should throw an error when fetch fails', async () => {
+            mockFetchAssociations.mockRejectedValueOnce(new Error('Network error'));
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expectError(request, 'Network error');
+        });
+        it('should handle unknown errors', async () => {
+            mockFetchAssociations.mockRejectedValueOnce('Unknown error');
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expectError(request, 'Failed to fetch associations: Unknown error');
+        });
+    });
+    describe('response validation', () => {
+        it('should throw error for invalid response format - missing results', async () => {
+            const invalidData = { hasMore: true, nextOffset: 0 }; // missing results
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(invalidData));
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expectError(request, 'Invalid response format');
+        });
+        it('should throw error for invalid response format - null data', async () => {
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(null));
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expectError(request, 'Invalid response format');
+        });
+        it('should throw error for invalid association result structure', async () => {
+            const invalidData = {
+                results: [{ invalidStructure: true }],
+                hasMore: false,
+                nextOffset: 0,
+            };
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(invalidData));
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expectError(request, 'Invalid response format');
+        });
+        it('should throw error for invalid association types array', async () => {
+            const invalidData = {
+                results: [
+                    {
+                        toObjectId: 1000,
+                        associationTypes: 'not an array',
+                        properties: {},
+                    },
+                ],
+                hasMore: false,
+                nextOffset: 0,
+            };
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(invalidData));
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expectError(request, 'Invalid response format');
+        });
+        it('should throw error for missing hasMore field', async () => {
+            const invalidData = {
+                results: [],
+                nextOffset: 0, // missing hasMore
+            };
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(invalidData));
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expectError(request, 'Invalid response format');
+        });
+    });
+    describe('API integration', () => {
+        it('should call self.fetchAssociations with correct parameters', async () => {
+            const emptyData = { results: [], hasMore: false, nextOffset: 0 };
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(emptyData));
+            const request = createBasicRequest({
+                properties: ['firstname'],
+                pageLength: 50,
+            });
+            await fetchAssociations(request);
+            expect(mockFetchAssociations).toHaveBeenCalledWith(request, undefined);
+        });
+        it('should return cleanup function from API response', async () => {
+            const mockCleanup = jest.fn();
+            const emptyData = { results: [], hasMore: false, nextOffset: 0 };
+            const mockApiResponse = { data: emptyData, cleanup: mockCleanup };
+            mockFetchAssociations.mockResolvedValueOnce({
+                ok: true,
+                json: jest.fn().mockResolvedValue(mockApiResponse),
+            });
+            const result = await fetchAssociations(createBasicRequest());
+            expect(result.cleanup).toBe(mockCleanup);
+            result.cleanup();
+            expect(mockCleanup).toHaveBeenCalledTimes(1);
+        });
+        it('should provide default cleanup function when none provided', async () => {
+            const emptyData = { results: [], hasMore: false, nextOffset: 0 };
+            const mockApiResponse = { data: emptyData }; // no cleanup function provided
+            mockFetchAssociations.mockResolvedValueOnce({
+                ok: true,
+                json: jest.fn().mockResolvedValue(mockApiResponse),
+            });
+            const result = await fetchAssociations(createBasicRequest());
+            expect(typeof result.cleanup).toBe('function');
+            expect(() => result.cleanup()).not.toThrow();
+        });
+        it('should successfully fetch associations with valid response', async () => {
+            const validData = {
+                results: [
+                    {
+                        toObjectId: 2000,
+                        associationTypes: [
+                            { category: 'HUBSPOT_DEFINED', typeId: 1, label: 'Primary' },
+                        ],
+                        properties: {
+                            firstname: 'John',
+                            lastname: 'Doe',
+                        },
+                    },
+                ],
+                hasMore: true,
+                nextOffset: 100,
+            };
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(validData));
+            const request = createBasicRequest();
+            const result = await fetchAssociations(request);
+            expect(mockFetchAssociations).toHaveBeenCalledWith(request, undefined);
+            expect(result.data).toEqual(validData);
+            expect(typeof result.cleanup).toBe('function');
+        });
+    });
+    describe('options handling', () => {
+        it('should pass formatting options to the underlying fetch function', async () => {
+            const emptyData = { results: [], hasMore: false, nextOffset: 0 };
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(emptyData));
+            const options = {
+                propertiesToFormat: ['firstname'],
+                formattingOptions: {
+                    date: { format: 'MM/dd/yyyy' },
+                    currency: { addSymbol: true },
+                },
+            };
+            const request = createBasicRequest();
+            await fetchAssociations(request, options);
+            expect(mockFetchAssociations).toHaveBeenCalledWith(request, options);
+        });
+        it('should handle propertiesToFormat set to "all"', async () => {
+            const emptyData = { results: [], hasMore: false, nextOffset: 0 };
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse(emptyData));
+            const options = {
+                propertiesToFormat: 'all',
+                formattingOptions: {
+                    dateTime: { relative: true },
+                },
+            };
+            const request = createBasicRequest();
+            await fetchAssociations(request, options);
+            expect(mockFetchAssociations).toHaveBeenCalledWith(request, options);
+        });
+        it('should preserve error handling with formatting options', async () => {
+            mockFetchAssociations.mockRejectedValueOnce(new Error('Network error'));
+            const options = {
+                propertiesToFormat: ['firstname'],
+                formattingOptions: {
+                    date: { format: 'MM/dd/yyyy' },
+                },
+            };
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expect(fetchAssociations(request, options)).rejects.toThrow('Network error');
+            expect(mockFetchAssociations).toHaveBeenCalledWith(request, options);
+        });
+        it('should preserve response validation with formatting options', async () => {
+            mockFetchAssociations.mockResolvedValueOnce(createMockResponse('Invalid response')); // data should be an object
+            const options = {
+                propertiesToFormat: 'all',
+            };
+            const request = createBasicRequest({ properties: ['firstname'] });
+            await expect(fetchAssociations(request, options)).rejects.toThrow('Invalid response format');
+        });
+    });
+});

package/dist/__tests__/experimental/crm/fetchCrmProperties.spec.js

@@ -70,6 +70,7 @@ describe('fetchCrmProperties', () => {
         const mockResponse = {
             ok: false,
             statusText: 'Not Found',
+            json: jest.fn().mockResolvedValue({}),
         };
         mockFetchCrmProperties.mockResolvedValue(mockResponse);
         const propertyNames = ['firstname'];

package/dist/__tests__/experimental/hooks/useAssociations.spec.d.ts

@@ -0,0 +1 @@
+export {};

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/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

@@ -19,6 +19,7 @@ export type FetchCrmPropertiesOptions = {
 };
 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>;

package/dist/experimental/crm/fetchCrmProperties.js

@@ -12,22 +12,27 @@ function isCrmPropertiesResponse(data) {
     return true;
 }
 export const fetchCrmProperties = async (propertyNames, propertiesUpdatedCallback, options) => {
+    let response;
+    let result;
     try {
         // eslint-disable-next-line hubspot-dev/no-confusing-browser-globals
-        const response = await self.fetchCrmProperties(propertyNames, propertiesUpdatedCallback, options);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch CRM properties: ${response.statusText}`);
-        }
-        const result = await response.json();
-        if (!isCrmPropertiesResponse(result.data)) {
-            throw new Error('Invalid response format');
-        }
-        return result;
+        response = await self.fetchCrmProperties(propertyNames, propertiesUpdatedCallback, options);
+        result = await response.json();
     }
     catch (error) {
-        if (error instanceof Error) {
-            throw error;
-        }
-        throw new Error('Failed to fetch CRM properties: Unknown error');
+        // Only handle network/parsing errors, not our validation errors
+        throw error instanceof Error
+            ? error
+            : new Error('Failed to fetch CRM properties: Unknown error');
     }
+    if (result.error) {
+        throw new Error(result.error);
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to fetch CRM properties: ${response.statusText}`);
+    }
+    if (!isCrmPropertiesResponse(result.data)) {
+        throw new Error('Invalid response format');
+    }
+    return result;
 };

package/dist/experimental/hooks/useAssociations.d.ts

@@ -0,0 +1,10 @@
+import { type FetchAssociationsRequest, type AssociationsResponse } from '../crm/fetchAssociations';
+import { type FetchCrmPropertiesOptions } from '../crm/fetchCrmProperties';
+export interface AssociationsState {
+    results: AssociationsResponse['results'];
+    error: Error | null;
+    isLoading: boolean;
+    hasMore: boolean;
+    nextOffset: number;
+}
+export declare function useAssociations(request: FetchAssociationsRequest, options?: FetchCrmPropertiesOptions): AssociationsState;

package/dist/experimental/hooks/useAssociations.js

@@ -0,0 +1,116 @@
+import { useEffect, useReducer, useMemo, useRef } from 'react';
+import { logger } from '../../logger';
+import { fetchAssociations, } from '../crm/fetchAssociations';
+const initialState = {
+    results: [],
+    error: null,
+    isLoading: true,
+    hasMore: false,
+    nextOffset: 0,
+};
+function associationsReducer(state, action) {
+    switch (action.type) {
+        case 'FETCH_START':
+            return {
+                ...state,
+                isLoading: true,
+                error: null,
+            };
+        case 'FETCH_SUCCESS':
+            return {
+                ...state,
+                isLoading: false,
+                results: action.payload.results,
+                hasMore: action.payload.hasMore,
+                nextOffset: action.payload.nextOffset,
+                error: null,
+            };
+        case 'FETCH_ERROR':
+            return {
+                ...state,
+                isLoading: false,
+                error: action.payload,
+                results: [],
+                hasMore: false,
+                nextOffset: 0,
+            };
+        default:
+            return state;
+    }
+}
+const DEFAULT_OPTIONS = {};
+export function useAssociations(request, options = DEFAULT_OPTIONS) {
+    const [state, dispatch] = useReducer(associationsReducer, initialState);
+    // Log experimental warning once on mount
+    useEffect(() => {
+        logger.warn('useAssociations is an experimental hook and might change or be removed in the future.');
+    }, []);
+    /**
+     * HOOK OPTIMIZATION:
+     *
+     * Create stable references for request and options to prevent unnecessary re-renders and API calls.
+     * Then, external developers can pass inline objects without worrying about memoization
+     * We handle the deep equality comparison ourselves, and return the same object reference when content is equivalent.
+     */
+    const lastRequestRef = useRef();
+    const lastRequestKeyRef = useRef();
+    const lastOptionsRef = useRef();
+    const lastOptionsKeyRef = useRef();
+    const stableRequest = useMemo(() => {
+        const requestKey = JSON.stringify(request);
+        if (requestKey === lastRequestKeyRef.current) {
+            return lastRequestRef.current;
+        }
+        lastRequestKeyRef.current = requestKey;
+        lastRequestRef.current = request;
+        return request;
+    }, [request]);
+    const stableOptions = useMemo(() => {
+        const optionsKey = JSON.stringify(options);
+        if (optionsKey === lastOptionsKeyRef.current) {
+            return lastOptionsRef.current;
+        }
+        lastOptionsKeyRef.current = optionsKey;
+        lastOptionsRef.current = options;
+        return options;
+    }, [options]);
+    // Fetch the associations
+    useEffect(() => {
+        let cancelled = false;
+        let cleanup = null;
+        const fetchData = async () => {
+            try {
+                dispatch({ type: 'FETCH_START' });
+                const result = await fetchAssociations(stableRequest, stableOptions);
+                if (!cancelled) {
+                    dispatch({
+                        type: 'FETCH_SUCCESS',
+                        payload: {
+                            results: result.data.results,
+                            hasMore: result.data.hasMore,
+                            nextOffset: result.data.nextOffset,
+                        },
+                    });
+                    cleanup = result.cleanup;
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    const errorData = err instanceof Error
+                        ? err
+                        : new Error('Failed to fetch associations');
+                    dispatch({ type: 'FETCH_ERROR', payload: errorData });
+                }
+            }
+        };
+        fetchData();
+        return () => {
+            cancelled = true;
+            // Call cleanup function to release resources
+            if (cleanup) {
+                cleanup();
+            }
+        };
+    }, [stableRequest, stableOptions]);
+    return state;
+}

package/dist/experimental/hooks/useCrmProperties.js

@@ -1,6 +1,37 @@
-import { useEffect, useState, useMemo, useRef } from 'react';
+import { useEffect, useReducer, useMemo, useRef } from 'react';
 import { logger } from '../../logger';
 import { fetchCrmProperties, } from '../crm/fetchCrmProperties';
+const initialState = {
+    properties: {},
+    error: null,
+    isLoading: true,
+};
+function crmPropertiesReducer(state, action) {
+    switch (action.type) {
+        case 'FETCH_START':
+            return {
+                ...state,
+                isLoading: true,
+                error: null,
+            };
+        case 'FETCH_SUCCESS':
+            return {
+                ...state,
+                isLoading: false,
+                properties: action.payload,
+                error: null,
+            };
+        case 'FETCH_ERROR':
+            return {
+                ...state,
+                isLoading: false,
+                error: action.payload,
+                properties: {},
+            };
+        default:
+            return state;
+    }
+}
 const DEFAULT_OPTIONS = {};
 /**
  * A hook for using and managing CRM properties.
@@ -8,9 +39,7 @@ const DEFAULT_OPTIONS = {};
  * @experimental This hook is experimental and might change or be removed in future versions.
  */
 export function useCrmProperties(propertyNames, options = DEFAULT_OPTIONS) {
-    const [properties, setProperties] = useState({});
-    const [isLoading, setIsLoading] = useState(true);
-    const [error, setError] = useState(null);
+    const [state, dispatch] = useReducer(crmPropertiesReducer, initialState);
     // Log experimental warning once on mount
     useEffect(() => {
         logger.warn('useCrmProperties is an experimental hook and might change or be removed in the future.');
@@ -51,11 +80,14 @@ export function useCrmProperties(propertyNames, options = DEFAULT_OPTIONS) {
         let cleanup = null;
         const fetchData = async () => {
             try {
-                setIsLoading(true);
-                setError(null);
-                const result = await fetchCrmProperties(stablePropertyNames, setProperties, stableOptions);
+                dispatch({ type: 'FETCH_START' });
+                const result = await fetchCrmProperties(stablePropertyNames, (data) => {
+                    if (!cancelled) {
+                        dispatch({ type: 'FETCH_SUCCESS', payload: data });
+                    }
+                }, stableOptions);
                 if (!cancelled) {
-                    setProperties(result.data);
+                    dispatch({ type: 'FETCH_SUCCESS', payload: result.data });
                     cleanup = result.cleanup;
                 }
             }
@@ -64,13 +96,7 @@ export function useCrmProperties(propertyNames, options = DEFAULT_OPTIONS) {
                     const errorData = err instanceof Error
                         ? err
                         : new Error('Failed to fetch CRM properties');
-                    setError(errorData);
-                    setProperties({});
-                }
-            }
-            finally {
-                if (!cancelled) {
-                    setIsLoading(false);
+                    dispatch({ type: 'FETCH_ERROR', payload: errorData });
                 }
             }
         };
@@ -83,9 +109,5 @@ export function useCrmProperties(propertyNames, options = DEFAULT_OPTIONS) {
             }
         };
     }, [stablePropertyNames, stableOptions]);
-    return {
-        properties,
-        error,
-        isLoading,
-    };
+    return state;
 }

package/dist/experimental/index.d.ts

@@ -1,6 +1,7 @@
 import type * as types from '../types';
 import type * as experimentalTypes from './types';
 export { useCrmProperties } from './hooks/useCrmProperties';
+export { useAssociations } from './hooks/useAssociations';
 /** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
 declare const Iframe: "Iframe" & {
     readonly type?: "Iframe" | undefined;
@@ -97,4 +98,22 @@ declare const CurrencyInput: "CurrencyInput" & {
     readonly props?: experimentalTypes.CurrencyInputProps | undefined;
     readonly children?: true | undefined;
 } & import("@remote-ui/react").ReactComponentTypeFromRemoteComponentType<import("@remote-ui/types").RemoteComponentType<"CurrencyInput", experimentalTypes.CurrencyInputProps, true>>;
-export { Iframe, MediaObject, Inline, Stack2, Center, SimpleGrid, GridItem, Grid, SettingsView, ExpandableText, Popover, FileInput, TimeInput, CurrencyInput, };
+/** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
+declare const HeaderActions: "HeaderActions" & {
+    readonly type?: "HeaderActions" | undefined;
+    readonly props?: experimentalTypes.HeaderActionsProps | undefined;
+    readonly children?: true | undefined;
+} & import("@remote-ui/react").ReactComponentTypeFromRemoteComponentType<import("@remote-ui/types").RemoteComponentType<"HeaderActions", experimentalTypes.HeaderActionsProps, true>>;
+/** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
+declare const PrimaryHeaderActionButton: "PrimaryHeaderActionButton" & {
+    readonly type?: "PrimaryHeaderActionButton" | undefined;
+    readonly props?: experimentalTypes.HeaderActionButtonProps | undefined;
+    readonly children?: true | undefined;
+} & import("@remote-ui/react").ReactComponentTypeFromRemoteComponentType<import("@remote-ui/types").RemoteComponentType<"PrimaryHeaderActionButton", experimentalTypes.HeaderActionButtonProps, true>>;
+/** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
+declare const SecondaryHeaderActionButton: "SecondaryHeaderActionButton" & {
+    readonly type?: "SecondaryHeaderActionButton" | undefined;
+    readonly props?: experimentalTypes.HeaderActionButtonProps | undefined;
+    readonly children?: true | undefined;
+} & import("@remote-ui/react").ReactComponentTypeFromRemoteComponentType<import("@remote-ui/types").RemoteComponentType<"SecondaryHeaderActionButton", experimentalTypes.HeaderActionButtonProps, true>>;
+export { Iframe, MediaObject, Inline, Stack2, Center, SimpleGrid, GridItem, Grid, SettingsView, ExpandableText, Popover, FileInput, TimeInput, CurrencyInput, HeaderActions, PrimaryHeaderActionButton, SecondaryHeaderActionButton, };

package/dist/experimental/index.js

@@ -1,5 +1,6 @@
 import { createRemoteReactComponent } from '@remote-ui/react';
 export { useCrmProperties } from './hooks/useCrmProperties';
+export { useAssociations } from './hooks/useAssociations';
 /** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
 const Iframe = createRemoteReactComponent('Iframe');
 /** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
@@ -42,4 +43,14 @@ const FileInput = createRemoteReactComponent('FileInput');
 const TimeInput = createRemoteReactComponent('TimeInput');
 /** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
 const CurrencyInput = createRemoteReactComponent('CurrencyInput');
-export { Iframe, MediaObject, Inline, Stack2, Center, SimpleGrid, GridItem, Grid, SettingsView, ExpandableText, Popover, FileInput, TimeInput, CurrencyInput, };
+/** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
+const HeaderActions = createRemoteReactComponent('HeaderActions');
+/** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
+const PrimaryHeaderActionButton = createRemoteReactComponent('PrimaryHeaderActionButton', {
+    fragmentProps: ['overlay'],
+});
+/** @experimental This component is experimental. Avoid using it in production due to potential breaking changes. Your feedback is valuable for improvements. Stay tuned for updates. */
+const SecondaryHeaderActionButton = createRemoteReactComponent('SecondaryHeaderActionButton', {
+    fragmentProps: ['overlay'],
+});
+export { Iframe, MediaObject, Inline, Stack2, Center, SimpleGrid, GridItem, Grid, SettingsView, ExpandableText, Popover, FileInput, TimeInput, CurrencyInput, HeaderActions, PrimaryHeaderActionButton, SecondaryHeaderActionButton, };

package/dist/experimental/types.d.ts

@@ -331,4 +331,25 @@ export interface CurrencyInputProps extends BaseInputForNumber {
      */
     max?: number;
 }
+/**
+ * @ignore
+ * @experimental do not use in production
+ */
+export interface HeaderActionsProps {
+    children: ReactNode;
+}
+/**
+ * @ignore
+ * @experimental do not use in production
+ */
+export interface HeaderActionButtonProps {
+    onClick?: ReactionsHandler<ExtensionEvent>;
+    href?: string | {
+        url: string;
+        external?: boolean;
+    };
+    disabled?: boolean;
+    children: ReactNode;
+    overlay?: RemoteFragment;
+}
 export {};

package/dist/types.d.ts

@@ -231,6 +231,10 @@ export interface SettingsActions {
     addAlert: AddAlertAction;
 }
 /** @ignore */
+export interface AppHomeActions {
+    addAlert: AddAlertAction;
+}
+/** @ignore */
 export interface UiePlatformActions {
     copyTextToClipboard: Clipboard['writeText'];
     closeOverlay: CloseOverlayAction;
@@ -2461,6 +2465,10 @@ export interface SettingsContext extends BaseContext {
     location: 'settings';
 }
 /** @ignore */
+export interface AppHomeContext extends BaseContext {
+    location: 'home';
+}
+/** @ignore */
 export interface GenericContext extends BaseContext {
     location: 'uie.playground.middle';
 }
@@ -2793,6 +2801,11 @@ export interface SettingsExtensionPoint extends ExtensionPointContract {
     actions: SettingsActions & UiePlatformActions;
     context: SettingsContext;
 }
+/** @ignore */
+export interface AppHomeExtensionPoint extends ExtensionPointContract {
+    actions: AppHomeActions;
+    context: AppHomeContext;
+}
 export interface ExampleCrmComponentProps {
     name: string;
     size: 'sm' | 'md' | 'lg';
@@ -2808,7 +2821,7 @@ interface RemotePlaygroundExtensionPoint extends ExtensionPointContract {
         ExampleCrmComponent: ComponentType<ExampleCrmComponentProps>;
     };
 }
-export declare const EXTENSION_POINT_LOCATIONS: readonly ["crm.preview", "crm.record.sidebar", "crm.record.tab", "helpdesk.sidebar", "uie.playground.middle", "settings"];
+export declare const EXTENSION_POINT_LOCATIONS: readonly ["crm.preview", "crm.record.sidebar", "crm.record.tab", "helpdesk.sidebar", "uie.playground.middle", "settings", "home"];
 export type ExtensionPointLocation = TypesOfReadOnlyArray<typeof EXTENSION_POINT_LOCATIONS>;
 /** @ignore */
 interface LocationToExtensionPoint {
@@ -2818,6 +2831,7 @@ interface LocationToExtensionPoint {
     'crm.record.sidebar': CrmSidebarExtensionPoint;
     'helpdesk.sidebar': StandardCrmExtensionPoint;
     settings: SettingsExtensionPoint;
+    home: AppHomeExtensionPoint;
 }
 /**
  * While this resolves to the same result as LocationToExtensionPoint, it ensures that every location

package/dist/types.js

@@ -235,6 +235,7 @@ export const EXTENSION_POINT_LOCATIONS = [
     'helpdesk.sidebar',
     'uie.playground.middle',
     'settings',
+    'home',
 ];
 /**
  * @category Serverless

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hubspot/ui-extensions",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "",
   "type": "module",
   "main": "dist/index.js",
@@ -66,5 +66,5 @@
     "ts-jest": "^29.1.1",
     "typescript": "5.0.4"
   },
-  "gitHead": "a5c7f8d19d0dc16b44e9235d3e12dacc2cc14fdf"
+  "gitHead": "65046f5f3ce4c51652bc454e4425b57bd33aedbf"
 }