@hubspot/ui-extensions-dev-server 1.1.6 → 1.1.8

package/dist/lib/DevServerState.d.ts

@@ -1,5 +1,5 @@
 import { AppConfig, ExtensionOutputConfig, ExtensionMetadata, Logger, PlatformVersion } from './types.ts';
-import { ServiceConfiguration, ProxyServiceConfig } from '@hubspot/app-functions-dev-server';
+import { ServiceConfiguration, ProxyServiceConfig } from './app-functions/types.ts';
 import { ExtensionsWebSocket } from './ExtensionsWebSocket.ts';
 type DevServerStateLocalDevUrlMapping = ProxyServiceConfig['localDevUrlMapping'] | undefined;
 interface DevServerStateArgs {

package/dist/lib/ExtensionsWebSocket.js

@@ -94,10 +94,34 @@ export class ExtensionsWebSocket {
         if (this.keepAliveIntervalId) {
             clearInterval(this.keepAliveIntervalId);
         }
+        /**
+         * To gracefully close client connections, we send a close frame and wait for the 'close' event.
+         * If the client doesn't respond within a reasonable timeout, we forcefully terminate it.
+         * This ensures we don't leave hanging connections and that resources are cleaned up properly.
+         */
+        const GRACEFUL_CLOSE_TIMEOUT_MS = 250;
+        const closePromises = [];
         this.wss.clients.forEach((client) => {
-            this.logger.debug('Terminating WebSocket client connection');
-            client.terminate();
+            this.logger.debug('Closing WebSocket client connection');
+            closePromises.push(new Promise((resolve) => {
+                if (client.readyState !== WebSocket.OPEN) {
+                    client.terminate();
+                    resolve();
+                    return;
+                }
+                const timeout = setTimeout(() => {
+                    client.terminate();
+                    resolve();
+                }, GRACEFUL_CLOSE_TIMEOUT_MS);
+                client.once('close', () => {
+                    clearTimeout(timeout);
+                    resolve();
+                });
+                // 1000 = Normal Closure status code
+                client.close(1000, 'Server shutting down');
+            }));
         });
+        await Promise.allSettled(closePromises);
         return new Promise((resolve, reject) => {
             this.wss.close((err) => {
                 if (err)

package/dist/lib/__tests__/ExtensionsWebSocket.spec.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach, } from 'vitest';
 import { ExtensionsWebSocket, isAllowedOrigin, } from "../ExtensionsWebSocket.js";
 import { DevServerState } from "../DevServerState.js";
 import { createMockLogger, createDevServerConfig } from "./factories.js";
@@ -7,7 +7,7 @@ let mockClients;
 let mockWss;
 let upgradeHandler = null;
 vi.mock('ws', () => ({
-    WebSocketServer: vi.fn(() => {
+    WebSocketServer: vi.fn(function WebSocketServer() {
         mockClients = new Set();
         const listeners = {};
         let isClosed = false;
@@ -42,6 +42,14 @@ vi.mock('ws', () => ({
 }));
 function createMockWebSocket() {
     const listeners = {};
+    const onceListeners = {};
+    function fireEvent(event, ...args) {
+        listeners[event]?.forEach((handler) => handler(...args));
+        if (onceListeners[event]) {
+            onceListeners[event].forEach((handler) => handler(...args));
+            onceListeners[event] = [];
+        }
+    }
     const mockWs = {
         readyState: 1,
         on: vi.fn((event, handler) => {
@@ -49,15 +57,19 @@ function createMockWebSocket() {
                 listeners[event] = [];
             listeners[event].push(handler);
         }),
-        once: vi.fn(),
+        once: vi.fn((event, handler) => {
+            if (!onceListeners[event])
+                onceListeners[event] = [];
+            onceListeners[event].push(handler);
+        }),
         emit: vi.fn((event, ...args) => {
-            listeners[event]?.forEach((handler) => handler(...args));
+            fireEvent(event, ...args);
         }),
         send: vi.fn(),
         close: vi.fn(() => {
             mockWs.readyState = 3;
             mockClients.delete(mockWs);
-            listeners['close']?.forEach((handler) => handler());
+            fireEvent('close');
         }),
         terminate: vi.fn(() => {
             mockWs.readyState = 3;
@@ -250,16 +262,24 @@ describe('ExtensionsWebSocket', () => {
             });
         });
         describe('close', () => {
-            it('should terminate all clients before closing', async () => {
+            it('should gracefully close all open clients', async () => {
                 extensionsWebSocket = new ExtensionsWebSocket(mockHttpServer, devServerState);
                 const { client: client1 } = simulateClientConnection();
                 const { client: client2 } = simulateClientConnection();
                 expect(extensionsWebSocket.clientCount).toBe(2);
                 await extensionsWebSocket.close();
-                expect(client1.terminate).toHaveBeenCalled();
-                expect(client2.terminate).toHaveBeenCalled();
+                expect(client1.close).toHaveBeenCalledWith(1000, 'Server shutting down');
+                expect(client2.close).toHaveBeenCalledWith(1000, 'Server shutting down');
                 expect(extensionsWebSocket.clientCount).toBe(0);
             });
+            it('should terminate clients that are not in OPEN state', async () => {
+                extensionsWebSocket = new ExtensionsWebSocket(mockHttpServer, devServerState);
+                const { client } = simulateClientConnection();
+                client.readyState = 2; // CLOSING
+                await extensionsWebSocket.close();
+                expect(client.terminate).toHaveBeenCalled();
+                expect(client.close).not.toHaveBeenCalled();
+            });
             it('should close the WebSocket server after clients disconnect', async () => {
                 extensionsWebSocket = new ExtensionsWebSocket(mockHttpServer, devServerState);
                 const { client } = simulateClientConnection();
@@ -290,6 +310,20 @@ describe('ExtensionsWebSocket', () => {
                 extensionsWebSocket.broadcast({ event: 'test' });
                 expect(devServerState.logger.debug).toHaveBeenCalledWith('No clients connected, message not sent');
             });
+            it('should forcibly terminate clients that do not close within timeout', async () => {
+                vi.useFakeTimers();
+                extensionsWebSocket = new ExtensionsWebSocket(mockHttpServer, devServerState);
+                const { client } = simulateClientConnection();
+                // Override close to NOT trigger the 'close' event (simulates unresponsive client)
+                client.close = vi.fn();
+                client.readyState = 1;
+                const closePromise = extensionsWebSocket.close();
+                // Advance past the graceful close timeout
+                vi.advanceTimersByTime(250);
+                await closePromise;
+                expect(client.close).toHaveBeenCalledWith(1000, 'Server shutting down');
+                expect(client.terminate).toHaveBeenCalled();
+            });
         });
         describe('error handlers', () => {
             it('should log WebSocket server errors', () => {

package/dist/lib/__tests__/app-functions/context.spec.d.ts

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

package/dist/lib/__tests__/app-functions/context.spec.js

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { Client } from '@hubspot/api-client';
+import { fetchObjectContext } from "../../app-functions/context.js";
+import { SAMPLE_BAD_REQUEST_API_ERROR, SAMPLE_NOT_FOUND_API_ERROR, SAMPLE_UNAUTHORIZED_API_ERROR, TEST_CONFIG_V20231 as TEST_CONFIG, } from "./fixtures/constants.js";
+/**
+ * Validate construction of the context (first argument in an app function)
+ */
+describe('context', () => {
+    const customObject = {
+        properties: {
+            name: 'The most custom of objects',
+            shouldBeFiltered: 'this should be filtered out, we do not want it',
+            mayOrMayNotBeFiltered: 'we might care about this',
+        },
+    };
+    const mockObjectApi = (getById) => {
+        vi.spyOn(Client.prototype, 'crm', 'get').mockReturnValue({
+            objects: {
+                basicApi: {
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    // @ts-ignore
+                    getById,
+                },
+            },
+        });
+    };
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('fetchObjectContext', () => {
+        it('should fetch objects using the correct endpoint', async () => {
+            mockObjectApi(() => Promise.resolve(customObject));
+            const objectQuery = {
+                objectId: 51,
+                objectTypeId: '0-2',
+                objectPropertyNames: ['name', 'mayOrMayNotBeFiltered'],
+            };
+            const result = await fetchObjectContext(TEST_CONFIG, objectQuery, 'pat-123');
+            const { name, mayOrMayNotBeFiltered } = customObject.properties;
+            expect(result.propertiesToSend).toStrictEqual({
+                name,
+                mayOrMayNotBeFiltered,
+            });
+        });
+        it('should throw a missing-token exception when access token is missing', async () => {
+            const objectQuery = {
+                objectId: 51,
+                objectTypeId: '0-2',
+                objectPropertyNames: ['name', 'mayOrMayNotBeFiltered'],
+            };
+            await expect(fetchObjectContext(TEST_CONFIG, objectQuery, undefined)).rejects.toThrow("Cannot fetch CRM object properties without a HubSpot API access token. This is not a problem with your code. Please copy the access token for your app at https://app.hubspot.com/private-apps/12345 and save it in an '.env' file in the 'app.functions' folder. For more details, please see https://developers.hubspot.com/docs/guides/crm/private-apps/serverless-functions.");
+        });
+        it('should throw a wrong-token exception when access token is invalid (401)', async () => {
+            mockObjectApi(() => {
+                throw SAMPLE_UNAUTHORIZED_API_ERROR;
+            });
+            const objectQuery = {
+                objectId: 51,
+                objectTypeId: '0-2',
+                objectPropertyNames: ['name', 'mayOrMayNotBeFiltered'],
+            };
+            await expect(fetchObjectContext(TEST_CONFIG, objectQuery, 'pat-123')).rejects.toThrow("Failed to fetch CRM object properties with objectTypeId~0-2 objectId~51 accountId~12345. Please check that the PRIVATE_APP_ACCESS_TOKEN specified in your '.env' file matches that of your app at https://app.hubspot.com/private-apps/12345.");
+        });
+        it('should throw a wrong-token exception when the object type id is invalid (400)', async () => {
+            mockObjectApi(() => {
+                throw SAMPLE_BAD_REQUEST_API_ERROR;
+            });
+            const objectQuery = {
+                objectId: 1999,
+                objectTypeId: '0-3-bad',
+                objectPropertyNames: ['name'],
+            };
+            await expect(fetchObjectContext(TEST_CONFIG, objectQuery, 'pat-123')).rejects.toThrow("Failed to fetch CRM object properties with objectTypeId~0-3-bad objectId~1999 accountId~12345. Please check that the PRIVATE_APP_ACCESS_TOKEN specified in your '.env' file matches that of your app at https://app.hubspot.com/private-apps/12345.");
+        });
+        it('should throw a wrong-token exception when the object id does not exist (404)', async () => {
+            mockObjectApi(() => {
+                throw SAMPLE_NOT_FOUND_API_ERROR;
+            });
+            const objectQuery = {
+                objectId: 1999,
+                objectTypeId: '0-1',
+                objectPropertyNames: ['name'],
+            };
+            await expect(fetchObjectContext(TEST_CONFIG, objectQuery, 'pat-123')).rejects.toThrow("Failed to fetch CRM object properties with objectTypeId~0-1 objectId~1999 accountId~12345. Please check that the PRIVATE_APP_ACCESS_TOKEN specified in your '.env' file matches that of your app at https://app.hubspot.com/private-apps/12345.");
+        });
+        it('should throw a generic exception for other errors', async () => {
+            mockObjectApi(() => {
+                throw new Error('Something else when wrong');
+            });
+            const objectQuery = {
+                objectId: 1999,
+                objectTypeId: '0-1',
+                objectPropertyNames: ['name'],
+            };
+            await expect(fetchObjectContext(TEST_CONFIG, objectQuery, 'pat-123')).rejects.toThrow(expect.objectContaining({
+                name: 'Error',
+                message: expect.stringContaining('Failed to fetch CRM object properties with objectTypeId~0-1 objectId~1999 accountId~12345:'),
+            }));
+        });
+    });
+});

package/dist/lib/__tests__/app-functions/errorReporter.spec.d.ts

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

package/dist/lib/__tests__/app-functions/errorReporter.spec.js

@@ -0,0 +1,102 @@
+import { vi, describe, beforeEach, afterEach, it, expect, } from 'vitest';
+const mockInit = vi.fn();
+const mockCaptureException = vi.fn();
+const mockWithScope = vi.fn((callback) => callback({ setTag: vi.fn(), setExtra: vi.fn() }));
+const mockFlush = vi.fn(() => Promise.resolve());
+vi.mock('@sentry/node', () => ({
+    init: mockInit,
+    captureException: mockCaptureException,
+    withScope: mockWithScope,
+    flush: mockFlush,
+}));
+describe('errorReporter', () => {
+    let reportError;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.resetModules();
+    });
+    describe('module initialization', () => {
+        it('initializes Sentry with correct DSN on import', async () => {
+            await import('../../app-functions/errorReporter.js');
+            expect(mockInit).toHaveBeenCalledWith(expect.objectContaining({
+                dsn: expect.stringContaining('exceptions.hubspot.com/v2/1'),
+            }));
+        });
+        it('includes version information in initialization', async () => {
+            await import('../../app-functions/errorReporter.js');
+            expect(mockInit).toHaveBeenCalledWith(expect.objectContaining({
+                release: expect.stringMatching(/@hubspot\/app-functions-dev-server@\d+\.\d+\.\d+/),
+                initialScope: expect.objectContaining({
+                    tags: expect.objectContaining({
+                        devServerVersion: expect.any(String),
+                    }),
+                }),
+            }));
+        });
+    });
+    describe('reportError', () => {
+        beforeEach(async () => {
+            const errorReporter = await import('../../app-functions/errorReporter.js');
+            reportError = errorReporter.reportError;
+        });
+        it('reports error with tags and extras', () => {
+            const testError = new Error('test error');
+            const context = {
+                errorType: 'internal_server_error',
+                functionName: 'testFunction',
+                appId: 123,
+                accountId: 456,
+            };
+            const mockSetTag = vi.fn();
+            const mockSetExtra = vi.fn();
+            mockWithScope.mockImplementationOnce((callback) => callback({ setTag: mockSetTag, setExtra: mockSetExtra }));
+            reportError(testError, context);
+            expect(mockSetTag).toHaveBeenCalledWith('errorType', 'internal_server_error');
+            expect(mockSetTag).toHaveBeenCalledWith('functionName', 'testFunction');
+            expect(mockSetTag).toHaveBeenCalledWith('appId', '123');
+            expect(mockSetTag).toHaveBeenCalledWith('accountId', '456');
+            expect(mockSetExtra).toHaveBeenCalledWith('errorContext', context);
+            expect(mockCaptureException).toHaveBeenCalledWith(testError);
+        });
+        it('reports error without context', () => {
+            const testError = new Error('test error');
+            reportError(testError);
+            expect(mockCaptureException).toHaveBeenCalledWith(testError);
+        });
+    });
+    describe('process error handlers', () => {
+        let mockExit;
+        beforeEach(async () => {
+            mockExit = vi
+                .spyOn(process, 'exit')
+                .mockImplementation(() => undefined);
+            await import('../../app-functions/errorReporter.js');
+        });
+        afterEach(() => {
+            mockExit.mockRestore();
+        });
+        it('captures uncaught exceptions and exits', async () => {
+            const error = new Error('uncaught error');
+            process.emit('uncaughtException', error);
+            await new Promise((resolve) => setImmediate(resolve));
+            expect(mockCaptureException).toHaveBeenCalledWith(error);
+            expect(mockFlush).toHaveBeenCalledWith(2000);
+            expect(mockExit).toHaveBeenCalledWith(1);
+        });
+        it('captures unhandled rejections and exits', async () => {
+            const reason = new Error('unhandled rejection');
+            process.emit('unhandledRejection', reason);
+            await new Promise((resolve) => setImmediate(resolve));
+            expect(mockCaptureException).toHaveBeenCalledWith(reason);
+            expect(mockFlush).toHaveBeenCalledWith(2000);
+            expect(mockExit).toHaveBeenCalledWith(1);
+        });
+        it('exits process even if flush fails', async () => {
+            mockFlush.mockImplementationOnce(() => Promise.reject(new Error('flush failed')));
+            const error = new Error('uncaught error');
+            process.emit('uncaughtException', error);
+            await new Promise((resolve) => setImmediate(resolve));
+            expect(mockExit).toHaveBeenCalledWith(1);
+        });
+    });
+});

package/dist/lib/__tests__/app-functions/executor_v20231.spec.d.ts

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

package/dist/lib/__tests__/app-functions/executor_v20231.spec.js

@@ -0,0 +1,168 @@
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import { Client } from '@hubspot/api-client';
+import { Reason, ExecutionError } from "../../app-functions/errors.js";
+import { executeFunction } from "../../app-functions/executor.js";
+import { NOOP_CALLBACK, TEST_CONFIG_V20231 as TEST_CONFIG, } from "./fixtures/constants.js";
+/**
+ * Validate function execution using sample functions defined in
+ * the app path of TEST_CONFIG, which is fixtures/app.functions/
+ */
+describe('app function executor', () => {
+    let actual;
+    const initialEnvJson = JSON.stringify(process.env);
+    const setActual = (value) => {
+        actual = value;
+    };
+    beforeEach(() => {
+        setActual(undefined);
+        // mock `apiClient.crm.objects.basicApi.getById` to return propertiesToSend for the CRM object
+        vi.spyOn(Client.prototype, 'crm', 'get').mockReturnValue({
+            objects: {
+                basicApi: {
+                    getById: () => 
+                    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                    // @ts-ignore
+                    Promise.resolve({
+                        properties: { firstname: 'First', lastname: 'Last' },
+                    }),
+                },
+            },
+        });
+    });
+    afterEach(() => {
+        vi.resetAllMocks();
+        // restore process.env
+        process.env = JSON.parse(initialEnvJson);
+    });
+    it('executes a function', async () => {
+        await executeFunction(TEST_CONFIG, 'returns-text', {}, setActual);
+        expect(actual).toEqual('result');
+    });
+    describe('handles inputs', () => {
+        it('none', async () => {
+            await executeFunction(TEST_CONFIG, 'echos-input', {}, setActual);
+            expect(actual).toEqual({
+                propertiesToSend: {},
+                parameters: undefined,
+                payload: undefined,
+            });
+        });
+        it('object query', async () => {
+            const inputs = {
+                objectQuery: {
+                    objectId: 51,
+                    objectTypeId: '0-1',
+                    objectPropertyNames: ['firstname', 'lastname'],
+                },
+            };
+            await executeFunction(TEST_CONFIG, 'echos-input', inputs, setActual);
+            expect(actual).toEqual({
+                propertiesToSend: { firstname: 'First', lastname: 'Last' },
+                parameters: undefined,
+                payload: undefined,
+            });
+        });
+        it('parameters', async () => {
+            const inputs = { parameters: { firstname: 'Wilbert' } };
+            await executeFunction(TEST_CONFIG, 'echos-input', inputs, setActual);
+            expect(actual).toEqual({
+                propertiesToSend: {},
+                parameters: { firstname: 'Wilbert' },
+                payload: undefined,
+            });
+        });
+        it('object query and parameters', async () => {
+            const inputs = {
+                objectQuery: {
+                    objectId: 51,
+                    objectTypeId: '0-1',
+                    objectPropertyNames: ['lastname'],
+                },
+                parameters: 'Salutations!',
+            };
+            await executeFunction(TEST_CONFIG, 'echos-input', inputs, setActual);
+            expect(actual).toEqual({
+                propertiesToSend: { lastname: 'Last' },
+                parameters: 'Salutations!',
+                payload: undefined,
+            });
+        });
+    });
+    describe('handles secrets', () => {
+        it('supplies secrets including the private app access token', async () => {
+            await executeFunction(TEST_CONFIG, 'uses-secret', {}, setActual);
+            expect(actual).toEqual({
+                contextSecrets: 'Listen up: ',
+                processEnvs: 'Listen up: Good dog!',
+            });
+        });
+        it('works with other inputs', async () => {
+            const inputs = { parameters: { PHRASE: 'Bella, ' } };
+            await executeFunction(TEST_CONFIG, 'uses-secret', inputs, setActual);
+            expect(actual).toEqual({
+                contextSecrets: 'Listen up: Bella, ',
+                processEnvs: 'Listen up: Bella, Good dog!',
+            });
+        });
+    });
+    it('throws an error if the function is not declared', async () => {
+        try {
+            await executeFunction(TEST_CONFIG, 'func-undeclared', {}, NOOP_CALLBACK);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ExecutionError);
+            expect(err.reason).toBe(Reason.FunctionNotFound);
+        }
+    });
+    it('throws an error if the function does not exist', async () => {
+        try {
+            await executeFunction(TEST_CONFIG, 'does-not-exist', {}, NOOP_CALLBACK);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ExecutionError);
+            expect(err.reason).toBe(Reason.FunctionNotFound);
+        }
+    });
+    it('throws an error if the function does not export main', async () => {
+        try {
+            await executeFunction(TEST_CONFIG, 'does-not-export-main', {}, NOOP_CALLBACK);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ExecutionError);
+            expect(err.reason).toBe(Reason.InvalidFunction);
+        }
+    });
+    it('throws an error if the function returns invalid json', async () => {
+        try {
+            await executeFunction(TEST_CONFIG, 'returns-function', {}, NOOP_CALLBACK);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ExecutionError);
+            expect(err.reason).toBe(Reason.InvalidResponse);
+        }
+    });
+    it('maps response undefined to null', async () => {
+        await executeFunction(TEST_CONFIG, 'returns-undefined', {}, setActual);
+        expect(actual).toBe(null);
+    });
+    it('throws an error if the function times out', async () => {
+        try {
+            await executeFunction(TEST_CONFIG, 'times-out', { parameters: { delayMs: 400 } }, NOOP_CALLBACK);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ExecutionError);
+            expect(err.reason).toBe(Reason.Timeout);
+        }
+    });
+    it('throws an error if the function throws an error', async () => {
+        try {
+            await executeFunction(TEST_CONFIG, 'throws-error', {}, NOOP_CALLBACK);
+        }
+        catch (err) {
+            expect(err).toBeInstanceOf(ExecutionError);
+            expect(err.reason).toBe(Reason.UncaughtError);
+            expect(err.cause).toBeInstanceOf(Error);
+            expect(err.cause).toHaveProperty('message', 'Oops');
+        }
+    });
+});

package/dist/lib/__tests__/app-functions/executor_v20232.spec.d.ts

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