@contentful/app-scripts 1.21.0 → 1.23.0

package/README.md

@@ -220,6 +220,32 @@ When passing the `--ci` argument adding all variables as arguments is required
 
 **Note:** You can also pass all arguments in interactive mode to skip being asked for it.
 
+### Install the AppDefinition into a specific space / environment
+
+It opens a dialog to select the space and environment where the app associated with the given [AppDefinition](https://www.contentful.com/developers/docs/extensibility/app-framework/app-definition/) should be installed.
+
+> **Example**
+>
+> ```shell
+> $ npx --no-install @contentful/app-scripts install --definition-id some-definition-id
+> ```
+
+You can also execute this command without the argument if the environment variable (`CONTENTFUL_APP_DEF_ID`) has been set.
+
+> **Example**
+>
+> ```shell
+> $ CONTENTFUL_APP_DEF_ID=some-definition-id npx --no-install @contentful/app-scripts install
+> ```
+
+By default, the script will install the app into the default host URL: `app.contentful.com`. If you want to install the app into a different host URL, you can set the argument `--host` to the desired host URL.
+
+> **Example**
+>
+> ```shell
+> $ npx --no-install @contentful/app-scripts install --definition-id some-definition-id --host api.eu.contentful.com
+> ```
+
 ### Tracking
 
 We gather depersonalized usage data of our CLI tools in order to improve experience. If you do not want your data to be gathered, you can opt out by providing an env variable `DISABLE_ANALYTICS` set to any value:

package/lib/analytics.js

@@ -26,7 +26,7 @@ function track({ command, ci }) {
                 command,
                 ci: String(ci),
             },
-            anonymousId: Date.now().toString(),
+            anonymousId: Date.now().toString(), // generate a random id
             timestamp: new Date(),
         });
         // eslint-disable-next-line no-empty

package/lib/bin.js

@@ -65,6 +65,14 @@ async function runCommand(command, options) {
         .action(async (options) => {
         await runCommand(feedback_1.feedback, options);
     });
+    commander_1.program
+        .command('install')
+        .description('Opens a picker to select the space and environment for installing the app associated with a given AppDefinition')
+        .option('--definition-id  [defId]', 'The id of your apps definition')
+        .option('--host [host]', 'Contentful domain to use')
+        .action(async (options) => {
+        await runCommand(index_1.install, options);
+    });
     commander_1.program.hook('preAction', (thisCommand) => {
         (0, index_1.track)({ command: thisCommand.args[0], ci: thisCommand.opts().ci });
     });

package/lib/constants.d.ts

@@ -6,3 +6,4 @@ export declare const DEFAULT_BUNDLES_TO_KEEP = 50;
 export declare const DEFAULT_BUNDLES_TO_FETCH = 1000;
 export declare const MAX_CONCURRENT_DELETION_CALLS = 5;
 export declare const DEFAULT_CONTENTFUL_API_HOST = "api.contentful.com";
+export declare const DEFAULT_CONTENTFUL_APP_HOST = "app.contentful.com";

package/lib/constants.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_CONTENTFUL_API_HOST = exports.MAX_CONCURRENT_DELETION_CALLS = exports.DEFAULT_BUNDLES_TO_FETCH = exports.DEFAULT_BUNDLES_TO_KEEP = exports.APP_DEF_ENV_KEY = exports.ORG_ID_ENV_KEY = exports.ACCESS_TOKEN_ENV_KEY = exports.DOTENV_FILE = void 0;
+exports.DEFAULT_CONTENTFUL_APP_HOST = exports.DEFAULT_CONTENTFUL_API_HOST = exports.MAX_CONCURRENT_DELETION_CALLS = exports.DEFAULT_BUNDLES_TO_FETCH = exports.DEFAULT_BUNDLES_TO_KEEP = exports.APP_DEF_ENV_KEY = exports.ORG_ID_ENV_KEY = exports.ACCESS_TOKEN_ENV_KEY = exports.DOTENV_FILE = void 0;
 exports.DOTENV_FILE = '.env';
 exports.ACCESS_TOKEN_ENV_KEY = 'CONTENTFUL_ACCESS_TOKEN';
 exports.ORG_ID_ENV_KEY = 'CONTENTFUL_ORG_ID';
@@ -9,3 +9,4 @@ exports.DEFAULT_BUNDLES_TO_KEEP = 50;
 exports.DEFAULT_BUNDLES_TO_FETCH = 1000;
 exports.MAX_CONCURRENT_DELETION_CALLS = 5;
 exports.DEFAULT_CONTENTFUL_API_HOST = 'api.contentful.com';
+exports.DEFAULT_CONTENTFUL_APP_HOST = 'app.contentful.com';

package/lib/create-app-definition/build-app-definition-settings.d.ts

@@ -1,8 +1,13 @@
-import { AppLocation, FieldType } from 'contentful-management';
+import { AppLocation, FieldType, ParameterDefinition, InstallationParameterType } from 'contentful-management';
 export interface AppDefinitionSettings {
     name: string;
     locations: AppLocation['location'][];
     fields?: FieldType[];
     host?: string;
+    buildAppParameters: boolean;
+    parameters?: {
+        instance: ParameterDefinition[];
+        installation: ParameterDefinition<InstallationParameterType>[];
+    };
 }
 export declare function buildAppDefinitionSettings(): Promise<AppDefinitionSettings>;

package/lib/create-app-definition/build-app-definition-settings.js

@@ -8,6 +8,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const inquirer_1 = __importDefault(require("inquirer"));
 const path_1 = __importDefault(require("path"));
 const constants_1 = require("../constants");
+const build_app_parameter_settings_1 = require("./build-app-parameter-settings");
 async function buildAppDefinitionSettings() {
     console.log(chalk_1.default.dim(`
 NOTE: This will create an app definition in your Contentful organization.
@@ -79,7 +80,16 @@ NOTE: This will create an app definition in your Contentful organization.
             message: `Contentful CMA endpoint URL:`,
             default: constants_1.DEFAULT_CONTENTFUL_API_HOST,
         },
+        {
+            name: 'buildAppParameters',
+            message: 'Would you like to specify App Parameter schemas? (see https://ctfl.io/app-parameters)',
+            type: 'confirm',
+            default: false,
+        },
     ]);
+    if (appDefinitionSettings.buildAppParameters) {
+        appDefinitionSettings.parameters = await (0, build_app_parameter_settings_1.buildAppParameterSettings)();
+    }
     appDefinitionSettings.locations = ['dialog', ...appDefinitionSettings.locations];
     return appDefinitionSettings;
 }

package/lib/create-app-definition/build-app-parameter-settings.d.ts

@@ -0,0 +1,5 @@
+import { InstallationParameterType, ParameterDefinition } from 'contentful-management';
+export declare function buildAppParameterSettings(): Promise<{
+    instance: ParameterDefinition[];
+    installation: ParameterDefinition<InstallationParameterType>[];
+}>;

package/lib/create-app-definition/build-app-parameter-settings.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAppParameterSettings = void 0;
+const inquirer_1 = __importDefault(require("inquirer"));
+const lodash_1 = require("lodash");
+const PARAMETER_ID_RE = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+const validateDefault = (input, type, options) => {
+    if (input === '')
+        return true;
+    switch (type) {
+        case 'Symbol':
+            return (0, lodash_1.isString)(input) || 'Default value must be a string.';
+        case 'Enum':
+            if (!(0, lodash_1.isString)(input))
+                return 'Default value must be a string.';
+            else if (options && !options.includes(input))
+                return 'Default value must be one of the options.';
+            return true;
+        case 'Number':
+            return (0, lodash_1.isNumber)(Number(input)) || 'Default value must be a number.';
+        case 'Boolean':
+            return input === 'true' || input === 'false' || 'Default value must be a boolean.';
+        default:
+            return true;
+    }
+};
+const validateEnumOptions = (input, type) => {
+    if (type !== 'Enum')
+        return true;
+    const allString = input.every(lodash_1.isString);
+    const allLabelled = input.every(lodash_1.isPlainObject);
+    return allString || allLabelled || 'Options should be all strings or all label objects.';
+};
+async function promptForParameter() {
+    const parameter = await inquirer_1.default.prompt([
+        {
+            name: 'instanceOrInstallation',
+            message: 'Is this an Instance or an Installation parameter?',
+            type: 'list',
+            choices: ['Instance', 'Installation'],
+        },
+        {
+            name: 'name',
+            message: 'Parameter name:',
+            validate(input) {
+                return input ? true : 'Parameter name is required.';
+            },
+        },
+        {
+            name: 'id',
+            message: 'Parameter ID:',
+            validate(input) {
+                if (!input)
+                    return 'Parameter ID is required.';
+                else if (!PARAMETER_ID_RE.test(input))
+                    return 'Parameter ID must start with a letter and contain only letters, numbers, and underscores.';
+                return true;
+            },
+        },
+        {
+            name: 'description',
+            message: 'Parameter description (optional):',
+        },
+        {
+            name: 'type',
+            message: 'Parameter type:',
+            type: 'list',
+            choices(answers) {
+                const parameterTypes = ['Boolean', 'Symbol', 'Number', 'Enum'];
+                // TODO uncomment when secret app installation parameters are finalized in the API
+                // if (answers.instanceOrInstallation === 'Installation') {
+                //   parameterTypes.push('Secret');
+                // }
+                return parameterTypes;
+            },
+        },
+        {
+            name: 'required',
+            message: 'Is this parameter required?',
+            type: 'confirm',
+            default: false,
+        },
+        {
+            name: 'options',
+            message: 'Parameter options (comma-separated) (optional):',
+            when(answers) {
+                return answers.type === 'Enum';
+            },
+            filter(input) {
+                return input ? input.split(',').map((opt) => opt.trim()) : [];
+            },
+            validate(input, answers) {
+                if (!input)
+                    return 'Options are required for Enum parameters.';
+                return validateEnumOptions(input, answers.type);
+            },
+        },
+        {
+            name: 'default',
+            message: 'Default value (leave blank if none):',
+            // TODO uncomment when secret app installation parameters are finalized in the API
+            // when(answers) {
+            //   return answers.type !== 'Secret';
+            // },
+            validate(input, answers) {
+                return validateDefault(input, answers.type, answers.options);
+            },
+        },
+        {
+            name: 'booleanLabels',
+            message: 'Parameter labels (true/false comma-separated) (optional):',
+            when(answers) {
+                return answers.type === 'Boolean';
+            },
+            filter(input) {
+                const labels = input ? input.split(',').map((label) => label.trim()) : [];
+                return JSON.stringify({
+                    true: labels[0] || '',
+                    false: labels[1] || '',
+                });
+            },
+        },
+        {
+            name: 'enumEmptyLabel',
+            message: 'Empty label (optional):',
+            filter(input) {
+                return JSON.stringify({
+                    empty: input.trim(),
+                });
+            },
+            when(answers) {
+                return answers.type === 'Enum';
+            },
+        },
+    ]);
+    return parameter;
+}
+async function buildAppParameterSettings() {
+    const parameters = {
+        instance: [],
+        installation: [],
+    };
+    let addMore = true;
+    while (addMore) {
+        try {
+            const parameter = await promptForParameter();
+            const labels = parameter.booleanLabels || parameter.enumEmptyLabel;
+            parameters[parameter.instanceOrInstallation.toLowerCase()].push({
+                id: parameter.id,
+                name: parameter.name,
+                description: parameter.description,
+                type: parameter.type,
+                required: parameter.required,
+                default: parameter.default,
+                options: parameter.options,
+                labels: labels ? JSON.parse(labels) : undefined,
+            });
+        }
+        catch (e) {
+            console.error('Failed to build parameter', e);
+        }
+        const { addAnother } = await inquirer_1.default.prompt({
+            name: 'addAnother',
+            message: 'Do you want to add another parameter?',
+            type: 'confirm',
+            default: false,
+        });
+        addMore = addAnother;
+    }
+    if ((0, lodash_1.uniq)(parameters.instance.map((p) => p.id)).length !== parameters.instance.length) {
+        console.log('Instance parameter IDs must be unique.');
+        return buildAppParameterSettings();
+    }
+    if ((0, lodash_1.uniq)(parameters.installation.map((p) => p.id)).length !== parameters.installation.length) {
+        console.log('Installation parameter IDs must be unique.');
+        return buildAppParameterSettings();
+    }
+    return parameters;
+}
+exports.buildAppParameterSettings = buildAppParameterSettings;

package/lib/create-app-definition/create-app-definition.js

@@ -33,7 +33,7 @@ function assertValidArguments(accessToken, appDefinitionSettings) {
         (0, utils_1.throwValidationException)('AccessToken', `Expected string got ${typeof accessToken}`);
     }
     if (!(0, lodash_1.isPlainObject)(appDefinitionSettings) || !(0, lodash_1.has)(appDefinitionSettings, 'locations')) {
-        (0, utils_1.throwValidationException)('AppDefinitionSettings', `Expected plain object with 'location' property, got ${JSON.stringify(appDefinitionSettings, null, 2)}`, `Example: ${JSON.stringify({
+        (0, utils_1.throwValidationException)('AppDefinitionSettings', `Expected plain object with 'locations' property, got ${JSON.stringify(appDefinitionSettings, null, 2)}`, `Example: ${JSON.stringify({
             name: 'app-name',
             locations: ['entry-field'],
             fields: [{ type: 'Boolean' }],
@@ -61,6 +61,14 @@ async function createAppDefinition(accessToken, appDefinitionSettings) {
                 location,
             };
         }),
+        parameters: {
+            ...(appDefinitionSettings.parameters?.instance && {
+                instance: appDefinitionSettings.parameters.instance,
+            }),
+            ...(appDefinitionSettings.parameters?.installation && {
+                installation: appDefinitionSettings.parameters.installation,
+            }),
+        },
     };
     try {
         const organization = await client.getOrganization(organizationId);

package/lib/get-app-info.d.ts

@@ -1,8 +1,8 @@
 export declare const getAppInfo: ({ organizationId, definitionId, token, host, }: {
-    organizationId?: string | undefined;
-    definitionId?: string | undefined;
-    token?: string | undefined;
-    host?: string | undefined;
+    organizationId?: string;
+    definitionId?: string;
+    token?: string;
+    host?: string;
 }) => Promise<{
     accessToken: string;
     organization: import("./organization-api").Organization;

package/lib/index.d.ts

@@ -5,3 +5,4 @@ export { cleanup } from './clean-up';
 export { open } from './open';
 export { track } from './analytics';
 export { feedback } from './feedback';
+export { install } from './install';

package/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.feedback = exports.track = exports.open = exports.cleanup = exports.activate = exports.upload = exports.createAppDefinition = void 0;
+exports.install = exports.feedback = exports.track = exports.open = exports.cleanup = exports.activate = exports.upload = exports.createAppDefinition = void 0;
 var create_app_definition_1 = require("./create-app-definition");
 Object.defineProperty(exports, "createAppDefinition", { enumerable: true, get: function () { return create_app_definition_1.createAppDefinition; } });
 var upload_1 = require("./upload");
@@ -15,3 +15,5 @@ var analytics_1 = require("./analytics");
 Object.defineProperty(exports, "track", { enumerable: true, get: function () { return analytics_1.track; } });
 var feedback_1 = require("./feedback");
 Object.defineProperty(exports, "feedback", { enumerable: true, get: function () { return feedback_1.feedback; } });
+var install_1 = require("./install");
+Object.defineProperty(exports, "install", { enumerable: true, get: function () { return install_1.install; } });

package/lib/install/index.d.ts

@@ -0,0 +1,5 @@
+import { InstallOptions } from '../types';
+export declare const install: {
+    interactive: (options: InstallOptions) => Promise<void>;
+    nonInteractive: () => Promise<never>;
+};

package/lib/install/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.install = void 0;
+const install_1 = require("./install");
+const interactive = async (options) => {
+    (0, install_1.installToEnvironment)(options);
+};
+const nonInteractive = async () => {
+    throw new Error(`"install" is not available in non-interactive mode`);
+};
+exports.install = {
+    interactive,
+    nonInteractive,
+};

package/lib/install/install.d.ts

@@ -0,0 +1,2 @@
+import { InstallOptions } from '../types';
+export declare function installToEnvironment(options: InstallOptions): Promise<void>;

package/lib/install/install.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installToEnvironment = void 0;
+const open_1 = __importDefault(require("open"));
+const chalk_1 = __importDefault(require("chalk"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const constants_1 = require("../constants");
+async function installToEnvironment(options) {
+    let definitionId;
+    if (options.definitionId) {
+        definitionId = options.definitionId;
+    }
+    else if (process.env[constants_1.APP_DEF_ENV_KEY]) {
+        definitionId = process.env[constants_1.APP_DEF_ENV_KEY];
+    }
+    else {
+        const prompts = await inquirer_1.default.prompt([
+            {
+                name: 'definitionId',
+                message: `The id of the app:`,
+            },
+        ]);
+        definitionId = prompts.definitionId;
+    }
+    if (!definitionId) {
+        console.log(`
+        ${chalk_1.default.red('Error:')} There was no app-definition defined.
+
+        Please add it with ${chalk_1.default.cyan('--definition-id=<app-definition-id>')}
+        or set the environment variable ${chalk_1.default.cyan(`${constants_1.APP_DEF_ENV_KEY} = <app-definition-id>`)}
+      `);
+        throw new Error('No app-definition-id');
+    }
+    const host = options.host || constants_1.DEFAULT_CONTENTFUL_APP_HOST;
+    const redirectUrl = `https://${host}/deeplink?link=apps`;
+    try {
+        (0, open_1.default)(`${redirectUrl}&id=${definitionId}`);
+    }
+    catch (err) {
+        console.log(`${chalk_1.default.red('Error:')} Failed to open browser`);
+        console.log(err.message);
+        throw err;
+    }
+}
+exports.installToEnvironment = installToEnvironment;

package/lib/types.d.ts

@@ -50,6 +50,10 @@ export interface CleanupSettings {
 export interface OpenSettingsOptions {
     definitionId?: string;
 }
+export interface InstallOptions {
+    definitionId?: string;
+    host?: string;
+}
 export interface UploadOptions {
     organizationId?: string;
     definitionId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/app-scripts",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "A collection of scripts for building Contentful Apps",
   "author": "Contentful GmbH",
   "license": "MIT",
@@ -48,11 +48,11 @@
   },
   "dependencies": {
     "@segment/analytics-node": "^2.0.0",
-    "adm-zip": "0.5.12",
+    "adm-zip": "0.5.14",
     "bottleneck": "2.19.5",
     "chalk": "4.1.2",
     "commander": "12.1.0",
-    "contentful-management": "11.26.2",
+    "contentful-management": "11.27.0",
     "dotenv": "16.4.5",
     "ignore": "5.3.1",
     "inquirer": "8.2.6",
@@ -60,16 +60,19 @@
     "open": "8.4.2",
     "ora": "5.4.1"
   },
-  "gitHead": "81cc3ea1a7090350e4791112816a82b243c3fc14",
+  "gitHead": "e6a2617d30e8d0cc1e78b7bf5edac5cd0543e532",
   "devDependencies": {
     "@tsconfig/node18": "18.2.4",
     "@types/adm-zip": "0.5.5",
     "@types/analytics-node": "3.1.14",
+    "@types/chai": "4.3.16",
     "@types/inquirer": "8.2.1",
-    "@types/lodash": "4.17.4",
+    "@types/lodash": "4.17.5",
     "@types/mocha": "10.0.6",
     "@types/proxyquire": "1.3.31",
     "@types/sinon": "17.0.3",
+    "chai": "5.1.1",
+    "mocha": "10.4.0",
     "proxyquire": "2.1.3",
     "sinon": "18.0.0",
     "ts-mocha": "10.0.0",