@hubspot/ui-extensions-dev-server 1.1.0 → 1.1.1

package/dist/lib/plugins/friendlyLoggingPlugin.js

@@ -0,0 +1,36 @@
+import path from 'path';
+const unfriendlyCodeMapper = Object.freeze({
+    UNRESOLVED_IMPORT: (loggable) => {
+        const { exporter, id } = loggable;
+        const { base: extension } = path.parse(id);
+        return {
+            message: `${exporter} is imported by ${extension}, but ${exporter} cannot be resolved. Make sure ${exporter} is installed by running \`hs project install-deps\`.`,
+            level: 'error',
+        };
+    },
+    MISSING_GLOBAL_NAME: () => {
+        return {};
+    },
+});
+const unfriendlyCodeList = Object.freeze(Object.keys(unfriendlyCodeMapper));
+function friendlyLoggingPlugin({ logger }) {
+    return {
+        name: 'ui-extensions-friendly-logging-plugin',
+        enforce: 'post',
+        onLog(_level, log) {
+            if (unfriendlyCodeList.includes(log.code || '')) {
+                const { message, level } = _mapMessageToFriendlyVersion(log);
+                if (message && level) {
+                    logger[level](message);
+                }
+                return false; // Filter the log message
+            }
+            return true; // We don't have a friendly log message, let it through
+        },
+    };
+}
+function _mapMessageToFriendlyVersion(loggable) {
+    const { code } = loggable;
+    return unfriendlyCodeMapper[code]?.(loggable) ?? {};
+}
+export default friendlyLoggingPlugin;

package/dist/lib/plugins/manifestPlugin.d.ts

@@ -0,0 +1,12 @@
+import { Rollup } from 'vite';
+import { Logger, ManifestConfig } from '../types.ts';
+export interface ManifestPluginOptions {
+    output: string;
+    minify?: boolean;
+    extensionPath?: string;
+    logger: Logger;
+    manifestConfig?: ManifestConfig;
+}
+export type ManifestPlugin = (options: ManifestPluginOptions) => Rollup.Plugin;
+declare const manifestPlugin: ManifestPlugin;
+export default manifestPlugin;

package/dist/lib/plugins/manifestPlugin.js

@@ -0,0 +1,158 @@
+import { readFileSync } from 'fs';
+import { normalize } from 'path';
+import { MANIFEST_FILE } from "../constants.js";
+import path from 'path';
+import { isExtensionFile, isNodeModule } from "../utils.js";
+import { traverseAbstractSyntaxTree } from "../ast.js";
+const PACKAGE_LOCK_FILE = 'package-lock.json';
+const PACKAGE_FILE = 'package.json';
+/**
+ * Checks if a given filename is a valid module file path. This is necessary because
+ * Rollup sometimes passes in a filename that starts with a null byte, which is not a valid
+ * module file path. From the Rollup documentation:
+ *
+ * > If your plugin uses 'virtual modules' (e.g. for helper functions), prefix the module ID with \0.
+ * > This prevents other plugins from trying to process it.
+ * Source: https://rollupjs.org/plugin-development/#conventions
+ *
+ * @param filename The filename to check.
+ * @returns Whether the filename is a valid module file path.
+ */
+const isRealModuleFile = (filename) => typeof filename === 'string' && !filename.startsWith('\0');
+const manifestPlugin = (options) => {
+    let allDataDependencies;
+    return {
+        name: 'ui-extensions-manifest-generation-plugin',
+        enforce: 'post', // run after default rollup plugins
+        buildStart() {
+            // Reset the source metadata for the new build
+            allDataDependencies = [];
+        },
+        transform(code, filename) {
+            const { logger } = options;
+            // We only need to parse the AST for extension files, so check that first.
+            const isExtension = isRealModuleFile(filename) &&
+                isExtensionFile(filename, options.extensionPath || '');
+            if (!isExtension) {
+                return { code, map: null };
+            }
+            try {
+                const ast = this.parse(code);
+                const sourceCodeMetadata = traverseAbstractSyntaxTree(ast, [], options.extensionPath || process.cwd(), logger);
+                allDataDependencies = [
+                    ...allDataDependencies,
+                    ...sourceCodeMetadata.dataDependencies.dependencies,
+                ];
+            }
+            catch (e) {
+                logger.error(`Unable to parse source code for ${filename}, ${e}`);
+            }
+            // We don't need to actually transform anything, just collect data, so return the original code
+            return { code, map: null };
+        },
+        generateBundle(_rollupOptions, bundle) {
+            const { output, minify = false, extensionPath = process.cwd(), logger, } = options;
+            try {
+                const filename = path.parse(output).name;
+                const manifest = _generateManifestContents(bundle, extensionPath, allDataDependencies, options?.manifestConfig);
+                this.emitFile({
+                    type: 'asset',
+                    source: minify
+                        ? JSON.stringify(manifest)
+                        : JSON.stringify(manifest, null, 2),
+                    fileName: normalize(`${filename}-${MANIFEST_FILE}`),
+                });
+            }
+            catch (e) {
+                logger.warn(`\nUnable to write manifest file in ${output}, ${e}`);
+            }
+        },
+    };
+};
+function _generateManifestContents(bundle, extensionPath, allDataDependencies, appConfig) {
+    const baseManifest = {
+        package: _loadPackageFile(extensionPath),
+    };
+    const dataDependencies = {
+        dataDeps: allDataDependencies ?? [],
+    };
+    const variables = {
+        variables: {},
+    };
+    if (appConfig &&
+        'variables' in appConfig &&
+        typeof appConfig.variables === 'object' &&
+        appConfig.variables !== null) {
+        variables.variables = appConfig.variables;
+    }
+    // The keys to bundle are the filename without any path information
+    const bundles = Object.keys(bundle).filter((cur) => cur.endsWith('.js'));
+    if (bundles.length === 1) {
+        return {
+            ..._generateManifestEntry(bundle[bundles[0]], extensionPath),
+            ...dataDependencies,
+            ...baseManifest,
+            ...variables,
+        };
+    }
+    const manifest = bundles.reduce((acc, current) => {
+        return {
+            ...acc,
+            [current]: _generateManifestEntry(bundle[current], extensionPath),
+        };
+    }, {});
+    return {
+        ...manifest,
+        ...dataDependencies,
+        ...baseManifest,
+        ...variables,
+    };
+}
+function _generateManifestEntry(subBundle, extensionPath) {
+    const { facadeModuleId, moduleIds, modules } = subBundle;
+    return {
+        entry: _stripPathPriorToExtDir(facadeModuleId, extensionPath),
+        modules: _buildModulesInfo(moduleIds, modules, extensionPath),
+    };
+}
+function _loadJsonFileSafely(extensionPath, filename) {
+    try {
+        return JSON.parse(readFileSync(path.join(extensionPath, filename)).toString());
+    }
+    catch (e) {
+        return undefined;
+    }
+}
+function _loadPackageFile(extensionPath) {
+    // Look for package-lock.json then fallback to package.json
+    return (_loadJsonFileSafely(extensionPath, PACKAGE_LOCK_FILE) ||
+        _loadJsonFileSafely(extensionPath, PACKAGE_FILE));
+}
+function _stripPathPriorToExtDir(filepath, extensionPath) {
+    // Before stripping the path, make sure the given extensionPath ends with a slash.
+    extensionPath = extensionPath.endsWith('/')
+        ? extensionPath
+        : `${extensionPath}/`;
+    return filepath?.split(extensionPath).pop();
+}
+function _buildModulesInfo(moduleIds, modules, extensionPath) {
+    const accumulator = {
+        internal: [],
+        external: [],
+    };
+    return moduleIds.reduce((acc, mod) => {
+        const { renderedExports } = modules[mod];
+        const moduleData = {
+            module: _stripPathPriorToExtDir(mod, extensionPath),
+            renderedExports,
+        };
+        if (isNodeModule(moduleData.module)) {
+            acc.external.push(moduleData);
+        }
+        else {
+            acc.internal.push(moduleData);
+        }
+        return acc;
+    }, accumulator);
+}
+export default manifestPlugin;

package/dist/lib/plugins/relevantModulesPlugin.d.ts

@@ -0,0 +1,13 @@
+import * as Vite from 'vite';
+import { Logger } from '../types.ts';
+export interface RelevantModules {
+    [key: string]: string[];
+}
+export declare function getRelevantModules(output: string): string[];
+export interface RelevantModulesPluginOptions {
+    output: string;
+    logger: Logger;
+}
+export type RelevantModulesPlugin = (options: RelevantModulesPluginOptions) => Vite.Plugin;
+declare const relevantModulesPlugin: RelevantModulesPlugin;
+export default relevantModulesPlugin;

package/dist/lib/plugins/relevantModulesPlugin.js

@@ -0,0 +1,25 @@
+import { isNodeModule } from "../utils.js";
+const relevantModules = {};
+export function getRelevantModules(output) {
+    return relevantModules[output] || [];
+}
+const relevantModulesPlugin = ({ output, logger }) => {
+    return {
+        name: 'ui-extensions-relevant-modules-plugin',
+        generateBundle(_options, bundle) {
+            const subBundle = bundle[output];
+            if (!subBundle || !subBundle.moduleIds) {
+                // If this happens, something has gone horribly wrong
+                logger.error('Invalid bundle format, please try saving the extension again.  If the problem persists try restarting `hs project dev`');
+                return;
+            }
+            const updatedRelevantModules = subBundle.moduleIds.filter((moduleId) => !isNodeModule(moduleId));
+            if (updatedRelevantModules.length === 0) {
+                logger.error('Unable to determine relevant files to watch, please try saving the extension again. If the problem persists try restarting `hs project dev`');
+                return;
+            }
+            relevantModules[output] = updatedRelevantModules;
+        },
+    };
+};
+export default relevantModulesPlugin;

package/dist/lib/server.d.ts

@@ -0,0 +1,13 @@
+import { Server } from 'http';
+import { ViteDevServer } from 'vite';
+import { DevServerState } from './DevServerState.ts';
+interface StartDevServerArgs {
+    devServerState: DevServerState;
+    viteDevServer: ViteDevServer;
+}
+interface StartDevServerReturn {
+    httpServer: Server;
+    shutdown: () => Promise<void>;
+}
+declare function startDevServer({ devServerState, viteDevServer, }: StartDevServerArgs): Promise<StartDevServerReturn>;
+export default startDevServer;

package/dist/lib/server.js

@@ -0,0 +1,99 @@
+import express from 'express';
+import cors from 'cors';
+import { PROXY_CAPABILITY, SERVER_CAPABILITIES } from "./constants.js";
+import extensionsService from "./extensionsService.js";
+import { AppFunctionExecutionService, AppProxyService, } from '@hubspot/app-functions-dev-server';
+import { extractAllowedUrls } from "./utils.js";
+import { ExtensionsWebSocket } from "./ExtensionsWebSocket.js";
+function listen(app, port) {
+    return new Promise((resolve, reject) => {
+        const server = app
+            .listen({ port }, () => {
+            resolve(server);
+        })
+            .on('error', (err) => {
+            reject(err);
+        });
+    });
+}
+async function startDevServer({ devServerState, viteDevServer, }) {
+    const app = express();
+    // Setup middleware
+    app.use(cors());
+    app.use(express.static(devServerState.outputDir));
+    const capabilities = [...SERVER_CAPABILITIES];
+    const middlewares = [];
+    if (!devServerState.isPublicApp()) {
+        middlewares.push(AppFunctionExecutionService({
+            ...devServerState.functionsConfig,
+            logger: devServerState.logger,
+        }));
+        devServerState.logger.info(`Serving app functions locally (platform version ${devServerState.functionsConfig.platformVersion})`);
+    }
+    if (devServerState.localDevUrlMapping &&
+        Object.keys(devServerState.localDevUrlMapping).length > 0) {
+        devServerState.logger.info('Proxy config discovered, enabling local proxy mode');
+        middlewares.push(AppProxyService({
+            localDevUrlMapping: devServerState.localDevUrlMapping,
+            logger: devServerState.logger,
+            accountId: devServerState.functionsConfig.accountId,
+            allowedUrls: extractAllowedUrls(devServerState.appConfig),
+        }));
+        capabilities.push(PROXY_CAPABILITY);
+    }
+    if (middlewares.length > 0) {
+        app.use('/api/crm-extensibility/execution/internal/v3', ...middlewares);
+    }
+    const endpointsAdded = extensionsService.add(app, devServerState, capabilities);
+    const { expressPort } = devServerState;
+    endpointsAdded.forEach((endpoint) => {
+        devServerState.logger.debug(`Listening at http://hslocal.net:${expressPort}${endpoint}`);
+    });
+    // Vite middlewares needs to go last because it's greedy and will block other middleware
+    app.use(viteDevServer.middlewares);
+    let server;
+    try {
+        server = await listen(app, devServerState.expressPort);
+    }
+    catch (e) {
+        if (e.code === 'EADDRINUSE') {
+            throw new Error(`Port ${devServerState.expressPort} is already in use.`);
+        }
+        throw new Error(e);
+    }
+    /**
+     * We use a custom WebSocket server instead of Vite's built-in one because:
+     * 1. We send HubSpot-specific extension metadata (not standard HMR messages)
+     * 2. We need cross-origin connections from HubSpot iframes
+     * 3. Our message format { event: 'start', ...metadata } doesn't match Vite's protocol
+     */
+    const wss = new ExtensionsWebSocket(server, devServerState);
+    devServerState.extensionsWebSocket = wss;
+    // Trigger the WebSocket setup that was deferred from the plugin's configureServer hook
+    // This must happen after the WebSocket is initialized to avoid race conditions
+    devServerState.triggerWebSocketSetup();
+    devServerState.extensionsMetadata?.forEach((metadata) => {
+        const { baseMessage } = metadata;
+        devServerState.logger.debug(`Listening at ${baseMessage.callback}`);
+    });
+    return {
+        httpServer: server,
+        shutdown: async function shutdown() {
+            try {
+                await viteDevServer.pluginContainer.close();
+                // Close WebSocket server first to reject new connections
+                await devServerState.getExtensionsWebSocket().close();
+                // Close HTTP server
+                await new Promise((resolve) => {
+                    server.close(() => resolve());
+                });
+                await viteDevServer.close();
+            }
+            catch (e) {
+                devServerState.logger.debug(`Error shutting down ${e}`);
+            }
+            devServerState.logger.info('Extension dev server done cleaning up');
+        },
+    };
+}
+export default startDevServer;

package/dist/lib/types.d.ts

@@ -0,0 +1,290 @@
+import { PLATFORM_VERSION, PRIVATE_APP, PUBLIC_APP } from './constants.ts';
+import { LocalDevUrlMapping } from '@hubspot/app-functions-dev-server';
+export interface ObjectTypes {
+    name: string;
+}
+export interface ExtensionConfig {
+    type: string;
+    data: {
+        title: string;
+        location: string;
+        module: {
+            file: string;
+        };
+        objectTypes: ObjectTypes[];
+        uid?: string;
+    };
+}
+export interface ExtensionOutputDataConfig {
+    appName: string;
+    title: string;
+    location: string;
+    module: {
+        file: string;
+    };
+    objectTypes: ObjectTypes[];
+    uid?: string;
+    sourceId?: string | null;
+}
+export interface ExtensionOutputConfig extends ExtensionConfig {
+    type: string;
+    output: string;
+    path: string;
+    extensionPath: string;
+    extensionConfigPath: string;
+    data: ExtensionOutputDataConfig;
+    appConfig?: AppConfig;
+}
+export interface ExtensionConfigMap {
+    [key: string]: ExtensionOutputConfig;
+}
+interface CardConfig {
+    file: string;
+}
+export interface ProjectConfig {
+    name: string;
+    srcDir: string;
+    platformVersion?: PlatformVersion;
+}
+export interface PrivateAppConfig {
+    name: string;
+    description: string;
+    scopes: string[];
+    public: boolean;
+    extensions: {
+        crm: {
+            cards: CardConfig[];
+        };
+    };
+    uid?: string;
+}
+export interface LocalAppConfig {
+    proxy: LocalDevUrlMapping;
+}
+export interface PublicAppAuth {
+    preventAdditionalScopes: boolean;
+    preventOptionalScopes: boolean;
+    redirectUrls: string[];
+    requiredScopes: string[];
+    optionalScopes: string[];
+    additionalScopes: string[];
+}
+export declare enum UnifiedAppAuthTypes {
+    OAUTH = "OAUTH",
+    STATIC = "STATIC"
+}
+export interface UnifiedAppAuth {
+    type: UnifiedAppAuthTypes;
+    redirectUrls?: string[];
+    requiredScopes?: string[];
+    optionalScopes?: string[];
+    conditionallyRequiredScopes?: string[];
+}
+export type AppAuth = PublicAppAuth | UnifiedAppAuth;
+export interface PublicAppConfig {
+    name: string;
+    uid: string;
+    logo?: string;
+    description?: string;
+    allowedUrls?: string[];
+    auth?: AppAuth;
+    support?: {
+        supportUrl: string;
+        supportEmail: string;
+        documentationUrl: string;
+        supportPhone: string;
+    };
+    extensions: {
+        crm: {
+            cards: CardConfig[];
+        };
+    };
+}
+export interface NonCanonicalAppMetadata {
+    isPublicApp?: boolean;
+}
+export type AppConfig = (PrivateAppConfig | PublicAppConfig) & NonCanonicalAppMetadata;
+export interface ProjectComponent {
+    type: typeof PUBLIC_APP | typeof PRIVATE_APP;
+    config: AppConfig;
+    path: string;
+}
+export interface ProjectComponentMap {
+    [key: string]: ProjectComponent;
+}
+export type UnifiedCardConfig = {
+    uid: string;
+    type: 'card';
+    config: {
+        name: string;
+        description?: string;
+        location: string;
+        entrypoint: string;
+        objectTypes?: string[];
+        previewImage?: {
+            file: string;
+            altText: string;
+        };
+    };
+};
+export declare enum UnifiedComponentTypes {
+    CARD = "CARD",
+    APPLICATION = "APPLICATION",
+    SETTINGS = "SETTINGS",
+    PAGE = "PAGE"
+}
+export type UnifiedExtensionComponent = Omit<UnifiedCardConfig, 'type'> & {
+    componentType: UnifiedComponentTypes.CARD | UnifiedComponentTypes.SETTINGS | UnifiedComponentTypes.PAGE;
+    componentDeps: {
+        app: string;
+    };
+    metaFilePath: string;
+    files: {};
+    localDev: {
+        componentRoot: string;
+        componentConfigPath: string;
+    };
+};
+export interface UnifiedAppComponent {
+    uid: string;
+    config: {
+        description: string;
+        name: string;
+        logo?: string;
+        auth: UnifiedAppAuth;
+        permittedUrls?: {
+            fetch: string[];
+            iframe: string[];
+            img: string[];
+        };
+        support?: {
+            supportEmail: string;
+            documentationUrl: string;
+            supportUrl: string;
+            supportPhone: string;
+        };
+        variables?: {
+            [key: string]: string | number | boolean;
+        };
+    };
+    componentType: UnifiedComponentTypes.APPLICATION;
+    componentDeps: {};
+    metaFilePath: string;
+    files: {};
+    localDev: {
+        componentRoot: string;
+        componentConfigPath: string;
+    };
+}
+export type UnifiedAppConfig = Omit<PublicAppConfig, 'auth'> & {
+    auth: UnifiedAppAuth;
+    isPublicApp: boolean;
+    variables?: {
+        [key: string]: string | number | boolean;
+    };
+};
+export type UnifiedComponent = UnifiedExtensionComponent | UnifiedAppComponent;
+export interface UnifiedProjectComponentMap {
+    [key: string]: UnifiedComponent;
+}
+export interface BaseMessage {
+    appName: string;
+    title: string;
+    callback: string;
+    sourceId?: string | null;
+    portalId?: number;
+}
+export interface ExtensionMetadata {
+    baseMessage: BaseMessage;
+    config: ExtensionOutputConfig;
+}
+export type PlatformVersion = (typeof PLATFORM_VERSION)[keyof typeof PLATFORM_VERSION];
+export interface FunctionMetadata {
+    scope?: 'Global' | 'Local';
+    defined?: boolean;
+    invoked?: boolean;
+}
+export type DataDependency = {
+    referenceId: string;
+    properties: {
+        type: 'CrmRecordProperties';
+        recordProperties: string[];
+        options: {
+            [key: string]: any;
+        };
+    } | {
+        type: 'CrmRecordAssociationProperties';
+        toObjectTypeId: string;
+        requestProperties: string[];
+        paginationOptions: {
+            [key: string]: any;
+        };
+        options: {
+            [key: string]: any;
+        };
+    };
+};
+export type NodeValue = string | number | boolean | null | undefined | RegExp | bigint | symbol | NodeValue[] | NodeObject;
+export type NodeObject = {
+    [key: string]: NodeValue;
+};
+export interface SourceCodeMetadata {
+    functions: {
+        [functionName: string]: FunctionMetadata;
+    };
+    badImports: string[];
+    dataDependencies: {
+        importedHooks: {
+            [hookName: string]: string;
+        };
+        dependencies: DataDependency[];
+    };
+    variableDeclarations: Map<string, NodeValue>;
+}
+export interface FunctionInvocationCheck {
+    functionName: string;
+}
+export type SourceCodeChecks = FunctionInvocationCheck[];
+export interface Logger {
+    info: (...args: any[]) => void;
+    debug: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+}
+export interface AppExtensionMapping {
+    name: string;
+    value: ExtensionOutputConfig;
+}
+export interface DevModeStartArguments {
+    accountId?: number;
+    requestPorts?: (requestPortsData: Array<{
+        instanceId: string;
+        port?: number;
+    }>) => Promise<{
+        [instanceId: string]: number;
+    }>;
+    projectConfig?: ProjectConfig;
+}
+export interface DevModeBaseSetupArguments {
+    onUploadRequired?: VoidFunction;
+    logger: Logger;
+    urls: {
+        api: string;
+        web: string;
+    };
+    setActiveApp: (appUid: string | undefined) => Promise<void>;
+    choices?: AppExtensionMapping[];
+}
+export interface DevModeSetupArguments extends DevModeBaseSetupArguments {
+    components: ProjectComponentMap;
+}
+export interface UnifiedDevModeSetupArguments extends DevModeBaseSetupArguments {
+    components: UnifiedProjectComponentMap;
+    profileData?: ProfileVariables;
+}
+export type ProfileVariableValue = string | number | boolean;
+export type ProfileVariables = Record<string, ProfileVariableValue>;
+export interface ManifestConfig {
+    variables?: ProfileVariables;
+}
+export {};

package/dist/lib/types.js

@@ -0,0 +1,12 @@
+export var UnifiedAppAuthTypes;
+(function (UnifiedAppAuthTypes) {
+    UnifiedAppAuthTypes["OAUTH"] = "OAUTH";
+    UnifiedAppAuthTypes["STATIC"] = "STATIC";
+})(UnifiedAppAuthTypes || (UnifiedAppAuthTypes = {}));
+export var UnifiedComponentTypes;
+(function (UnifiedComponentTypes) {
+    UnifiedComponentTypes["CARD"] = "CARD";
+    UnifiedComponentTypes["APPLICATION"] = "APPLICATION";
+    UnifiedComponentTypes["SETTINGS"] = "SETTINGS";
+    UnifiedComponentTypes["PAGE"] = "PAGE";
+})(UnifiedComponentTypes || (UnifiedComponentTypes = {}));

package/dist/lib/utils.d.ts

@@ -0,0 +1,25 @@
+import { AppConfig, ExtensionConfig } from './types.ts';
+export declare function getUrlSafeFileName(filePath: string): string;
+export declare function stripAnsiColorCodes(stringWithColorCodes: string | undefined | null): string | null;
+export declare function loadManifest(outputDir: string, output: string): any;
+export declare function buildSourceId(appConfig: AppConfig, extensionConfig: ExtensionConfig): string | null;
+export declare function isNodeModule(filepath: string | undefined): boolean;
+/**
+ * Check if a given file is within the extension path
+ */
+export declare function isExtensionFile(filepath: string | undefined, extensionPath: string): boolean;
+export declare class UnhandledPlatformVersionError extends Error {
+    constructor(platformVersion: never);
+}
+export declare function throwUnhandledPlatformVersionError(platformVersion: never): never;
+export declare function extractAllowedUrls(appConfig?: AppConfig): string[];
+/**
+ * This function generates a deterministic hash from any number of arguments
+ * Arrays and objects are stringified to ensure it works for all types.
+ * Uses the same simple hash algorithm as the browser version for consistency.
+ */
+export declare function generateHash(...args: unknown[]): string;
+/**
+ * Check if a given URL is an image (of a type we support)
+ */
+export declare function isImage(url: string): boolean;