@pendo/agent 2.281.0 → 2.282.0

package/README.md

@@ -95,21 +95,24 @@ The current list of available plugins and their export names are:
 
 Writing an extension that adheres to the strict requirements of Manifest V3 can sometimes be challenging. If you have a Manifest V3 extension that you would like to install Pendo into, in order to understand how your customers use your extension, you will need to follow a few steps to ensure that the Pendo agent does not fetch any remote code. Using this npm package is the most straightforward way to include all Pendo assets in your extension.
 
-1. Use the [CLI](#cli) to copy the agent static files into a folder that will be included in your packaged extension (ensure this is run each time you update your agent version).
+1. Use the [CLI](#cli) to copy the agent static files, using the `copy` command, into a folder that will be included in your packaged extension (ensure this is run each time you update your agent version).
+1. Use the [CLI](#cli) to download copies of the designer plugin files, using the `designer` command, into your packaged extension (ensure this runs each time you rebuild your extension to ensure you have the latest designer code).
 1. Update the `manifest.json` file to include those copied files in your "web_accessible_resources". The files copied are: "guide.css", "pendo.debugger.min.js", "debugger-plugin.min.js", "pendo.preview.min.js", "replay.worker.min.js" (the worker is only needed if using Pendo Session Replay)
 1. Initialize Pendo on the desired page or pages with any desired options, making sure to use the [assets option](#assets).
-1. The "host" field will need to be the extension resource url. It will probably look like this: `chrome.runtime.getURL('').slice(0, -1)`
+1. The "host" field will need to be the extension resource url. You can use a code snippet like this to properly retrieve that url: `chrome.runtime.getURL('').slice(0, -1)`
 1. The "path" field will need to be set to whatever the folder the assets were copied to. If they are in the root of your packaged extension this can be an empty string but if, for example, those assets are in a folder called `pendo`, the "path" would just be `pendo`.
-1. The "localOnly" field will need to be set `true` in your final packaged extension. This does mean that you will not be able to launch the designer in the store version of your extension however. In order to utilize Visual Design Studio you will need to use a dev unpackaged version of your extension where "localOnly" is either not set or set to `false`.
+1. The "localOnly" field will need to be set `true` in order to disable remote code execution and allow the designer to launch using your extension's files.
+
+We have created an [example extension](https://github.com/pendo-io/chrome-mv3-example) to show what a basic setup might look like.
 
 ## CLI
 
 The Pendo package includes a CLI tool to be able to simplify a few actions providing greater control of the Pendo Agent in your application. Once you have installed `@pendo/agent` in your application, you will have access to the `pendo` script from your terminal (you can also use a tool like `npx` to make use of the `pendo` script without installing the package if desired by using `npx pendo`). The usage of this script can be found below or by typing `pendo` or `pendo help` into your terminal where the package is installed:
 
-> **Note**: If the config and copy commands are being used by your application, you might want to use those as part of your regular build process to ensure that you always maintain up to date versions of your config and of the static assets. For example, you could add a script to your package.json like below that you then call as part of your build:
+> **Note**: If the config, copy, or designer commands are being used by your application, you might want to use those as part of your regular build process to ensure that you always maintain up to date versions of your config and of the static assets. For example, you could add a script to your package.json like below that you then call as part of your build:
 
 ```json
-"pendo-build": "pendo copy --dest=public && pendo config --apiKey={{APIKEY}} --env={{YOUR_ENV}}",
+"pendo-build": "pendo copy --dest=public && pendo config --apiKey={{APIKEY}} --env={{YOUR_ENV}} && pendo designer --dest=public --env={{YOUR_ENV}}",
 ```
 
 ### Help
@@ -162,3 +165,19 @@ Examples:
     Copy from the default location to your public folder
     $ pendo copy --dest=public
 ```
+
+### Download Designer Plugins
+
+```bash
+Usage: pendo designer --env=<subscription_environment> --dest=<destination_folder>
+
+Download new copies of the plugin files needed for the Visual Design Studio to launch and operate correctly.
+
+Options:
+    --env         required, the Pendo environment for your subscription, allowed environments: [${environments}]
+    --dest        required, the destination folder to copy the static files to, usually the "public" folder of your application
+
+Examples:
+    Download and save the designer files from the default US environment
+    $ pendo designer --env=io --dest=public`
+```

package/bin/cli.js

@@ -4,6 +4,7 @@ import minimist from 'minimist';
 import https from 'https';
 import fs from 'fs';
 import path from 'path';
+import zlib from 'zlib';
 
 const options = minimist(process.argv.slice(2));
 
@@ -24,7 +25,6 @@ function config() {
         options.output = 'pendo.config.json';
     }
 
-    const file = fs.createWriteStream(options.output);
     const url = new URL(`agent/static/${options.apiKey}/config.json`, `https://${servers.assetHost[options.env]}`).toString();
     try {
         https.get(url, function(response) {
@@ -38,17 +38,12 @@ function config() {
                 delete config.stagingAgentUrl;
                 delete config.stagingServerHashes;
                 delete config.stagingServers;
-            });
-
-            response.pipe(file);
-
-            file.on('finish', () => {
-                file.close();
+                fs.writeFileSync(options.output, JSON.stringify(config, null, 4), 'utf8');
                 console.debug('Pendo Agent config downloaded successfully');
             });
         });
     } catch (err) {
-        console.error(`Unable to download new Pendo Agent config file, please confirm the apiKey and contentHost. apiKey=${options.apiKey}, contentHost=${options.contentHost}`);
+        console.error(`Unable to download new Pendo Agent config file, please confirm the apiKey and contentHost. apiKey=${options.apiKey}, contentHost=${options.contentHost}`, err);
     }
 }
 
@@ -109,6 +104,77 @@ Examples:
     $ pendo copy --dest=public`);
 }
 
+function designer() {
+    const servers = JSON.parse(fs.readFileSync(new URL('../dist/servers.json', import.meta.url), 'utf8'));
+    if (!options.env || !servers.ENV[options.env]) {
+        console.error('Missing or invalid option "env", please provide a valid environment for your subscription using the "--env=" parameter');
+        console.error('\nExample: $ pendo designer --env=io');
+        process.exit(1);
+    }
+    if (!options.dest || typeof options.dest !== 'string') {
+        console.error('Missing required option "dest" to save designer plugin files to, please provide the destination folder for your project using the "--dest=" parameter.');
+        console.error('\nExample: $ pendo designer --dest=public');
+        process.exit(1);
+    }
+
+    const designerFiles = ['plugin.js', 'preloader.js'];
+
+    designerFiles.forEach(filename => {
+        try {
+            const pluginUrl = new URL(`in-app-designer/latest/${filename}`, `${servers.data[options.env]}`).toString();
+            const filePath = path.join(options.dest, filename);
+            const file = fs.createWriteStream(filePath);
+
+            const requestOptions = {
+                headers: {
+                    'Accept-Encoding': 'gzip'
+                }
+            };
+
+            https.get(pluginUrl, requestOptions, function(response) {
+                let error;
+
+                if (response.headers['content-encoding'] === 'gzip') {
+                    response = response.pipe(zlib.createGunzip());
+                }
+
+                response.pipe(file);
+
+                response.on('error', () => {
+                    error = true;
+                    file.close();
+                });
+
+                file.on('finish', () => {
+                    file.close();
+                    if (error) {
+                        console.debug(`Error downloading Pendo Visual Design Studio ${filename}, please confirm the environment and destination. env=${options.env}, dest=${options.dest}`);
+                    } else {
+                        console.debug(`Pendo Visual Design Studio ${filename} downloaded successfully`);
+                    }
+                });
+            });
+        } catch (err) {
+            console.error(`Unable to download new Pendo designer plugin file ${filename}, please confirm the environment and destination. env=${options.env}, dest=${options.dest}`, err);
+        }
+    });
+}
+
+function designerHelp() {
+    const environments = Object.keys(JSON.parse(fs.readFileSync(new URL('../dist/servers.json', import.meta.url), 'utf8')).ENV);
+    console.log(`Usage: pendo designer --env=<subscription_environment> --dest=<destination_folder>
+
+Download new copies of the plugin files needed for the Visual Design Studio to launch and operate correctly.
+
+Options:
+    --env         required, the Pendo environment for your subscription, allowed environments: [${environments}]
+    --dest        required, the destination folder to copy the static files to, usually the "public" folder of your application
+
+Examples:
+    Download and save the designer files from the default US environment
+    $ pendo designer --env=io --dest=public`);
+}
+
 function version() {
     const packageFile = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
     console.log(packageFile.version);
@@ -121,9 +187,10 @@ Show the current version of the Pendo Agent installed.`);
 }
 
 const helpers = {
-    'config':  configHelp,
-    'copy':    copyHelp,
-    'version': versionHelp
+    config: configHelp,
+    copy: copyHelp,
+    designer: designerHelp,
+    version: versionHelp
 };
 
 function help() {
@@ -137,6 +204,7 @@ CLI for @pendo/agent to assist in integrating the Pendo Agent into your applicat
 Commands:
     pendo config            download a new Pendo Agent configuration file for your application
     pendo copy              copy static assets for the Pendo Agent to a static folder
+    pendo designer          download new copies of the plugin files needed for the Visual Design Studio
     pendo help              provide help for how to use the Pendo CLI
     pendo help <command>    search for help on a specific <command>
     pendo version           show the current version of the Pendo Agent
@@ -157,6 +225,7 @@ Documentation for the Pendo Agent can be found at:
 const commands = {
     config,
     copy,
+    designer,
     help,
     version
 };