@salesforce/packaging 0.0.13 → 0.0.14

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.14](https://github.com/forcedotcom/packaging/compare/v0.0.13...v0.0.14) (2022-08-05)
+
+### Bug Fixes
+
+- adds package install ([97a821a](https://github.com/forcedotcom/packaging/commit/97a821af4e427b413e59c55143d5f17df0513dcc))
+- adds some package install code ([f2fff8e](https://github.com/forcedotcom/packaging/commit/f2fff8e52a498c70230575b1ace3a6f303168ad4))
+- enable install NUTs ([105250b](https://github.com/forcedotcom/packaging/commit/105250bbabe0185c04dab9cff2c9d17be4dd488f))
+- export getStatus and add validateId function ([8a97c4a](https://github.com/forcedotcom/packaging/commit/8a97c4ac2a58ad7992f0d37f74fcf4662f754793))
+- use install key ([457d777](https://github.com/forcedotcom/packaging/commit/457d7779f3e646f71b5faf1adc913094c524b74a))
+
 ### [0.0.13](https://github.com/forcedotcom/packaging/compare/v0.0.12...v0.0.13) (2022-08-05)
 
 ### Bug Fixes

package/lib/constants.d.ts

@@ -18,4 +18,6 @@ export declare const consts: {
     PACKAGE_VERSION_INFO_FILE_ZIP: string;
     INSTANCE_URL_TOKEN: string;
     PACKAGE2_DESCRIPTOR_FILE: string;
+    PACKAGE_INSTALL_POLL_FREQUENCY: number;
+    PACKAGE_INSTALL_POLL_TIMEOUT: number;
 };

package/lib/constants.js

@@ -36,5 +36,7 @@ exports.consts = {
     // tokens to be replaced on source:push
     INSTANCE_URL_TOKEN: '__SFDX_INSTANCE_URL__',
     PACKAGE2_DESCRIPTOR_FILE: 'package2-descriptor.json',
+    PACKAGE_INSTALL_POLL_FREQUENCY: 5000,
+    PACKAGE_INSTALL_POLL_TIMEOUT: 5, // 5 minutes
 };
 //# sourceMappingURL=constants.js.map

package/lib/interfaces/packagingInterfacesAndType.d.ts

@@ -1,17 +1,21 @@
 import { Duration } from '@salesforce/kit';
 import { Connection, SfProject } from '@salesforce/core';
-import { SaveResult } from 'jsforce';
+import { QueryResult, SaveResult } from 'jsforce';
 import { PackageProfileApi } from '../package/packageProfileApi';
 import { PackagingSObjects } from './packagingSObjects';
 import Package2VersionStatus = PackagingSObjects.Package2VersionStatus;
+import PackageInstallRequest = PackagingSObjects.PackageInstallRequest;
 export interface IPackage {
     create(): Promise<void>;
     convert(): Promise<void>;
     delete(): Promise<void>;
-    install(): Promise<void>;
-    list(): Promise<void>;
+    install(pkgInstallCreateRequest: PackageInstallCreateRequest, options?: PackageInstallOptions): Promise<PackageInstallRequest>;
+    getInstallStatus(installRequestId: string): Promise<PackageInstallRequest>;
+    list(): Promise<QueryResult<PackagingSObjects.Package2>>;
     uninstall(): Promise<void>;
     update(): Promise<void>;
+    waitForPublish(subscriberPackageVersionKey: string, timeout: number | Duration, installationKey?: string): any;
+    getExternalSites(subscriberPackageVersionKey: string, installationKey?: string): any;
 }
 export interface IPackageVersion1GP {
     create(): Promise<void>;
@@ -31,7 +35,10 @@ export interface IPackageVersion2GP {
     uninstall(): Promise<void>;
     update(): Promise<void>;
 }
-export declare type PackageOptions = Record<string, unknown>;
+export declare type PackageOptions = {
+    connection: Connection;
+};
+export declare type PackageIdType = 'PackageId' | 'SubscriberPackageVersionId' | 'PackageInstallRequestId' | 'PackageUninstallRequestId';
 export declare type PackageVersionOptions1GP = Record<string, unknown>;
 export declare type PackageVersionCreateRequestResult = {
     Id: string;
@@ -92,6 +99,7 @@ export declare type PackageVersionListResult = {
     BuildDurationInSeconds?: number;
     HasMetadataRemoved?: boolean;
 };
+export declare type PackageInstallCreateRequest = Partial<Pick<PackageInstallRequest, 'ApexCompileType' | 'EnableRss' | 'NameConflictResolution' | 'PackageInstallSource' | 'Password' | 'SecurityType' | 'UpgradeType'>> & Pick<PackagingSObjects.PackageInstallRequest, 'SubscriberPackageVersionKey'>;
 export declare type Package1Display = {
     MetadataPackageVersionId: string;
     MetadataPackageId: string;
@@ -130,6 +138,18 @@ export declare type PackageVersionCreateRequestOptions = {
     branch?: string;
     skipancestorcheck?: boolean;
 };
+export declare type PackageInstallOptions = {
+    /**
+     * The frequency to poll the org for package installation status. If providing a number
+     * it is interpreted in milliseconds.
+     */
+    pollingFrequency?: number | Duration;
+    /**
+     * The amount of time to wait for package installation to complete. If providing a number
+     * it is interpreted in minutes.
+     */
+    pollingTimeout?: number | Duration;
+};
 export declare type MDFolderForArtifactOptions = {
     packageName?: string;
     sourceDir?: string;

package/lib/interfaces/packagingSObjects.d.ts

@@ -1,3 +1,4 @@
+import { Nullable } from '@salesforce/ts-types';
 import { PackageType } from './packagingInterfacesAndType';
 export declare namespace PackagingSObjects {
     type Package2 = {
@@ -118,6 +119,20 @@ export declare namespace PackagingSObjects {
     type SubscriberPackageDependencies = {
         ids: string[];
     };
+    type SubscriberPackageRemoteSiteSetting = {
+        secure: boolean;
+        url: string;
+    };
+    type SubscriberPackageRemoteSiteSettings = {
+        settings: SubscriberPackageRemoteSiteSetting[];
+    };
+    type SubscriberPackageCspTrustedSite = {
+        endpointUrl: string;
+    };
+    type SubscriberPackageCspTrustedSites = {
+        settings: SubscriberPackageCspTrustedSite[];
+    };
+    type InstallValidationStatus = 'NO_ERRORS_DETECTED' | 'BETA_INSTALL_INTO_PRODUCTION_ORG' | 'CANNOT_INSTALL_EARLIER_VERSION' | 'CANNOT_UPGRADE_BETA' | 'CANNOT_UPGRADE_UNMANAGED' | 'DEPRECATED_INSTALL_PACKAGE' | 'EXTENSIONS_ON_LOCAL_PACKAGES' | 'PACKAGE_NOT_INSTALLED' | 'PACKAGE_HAS_IN_DEV_EXTENSIONS' | 'INSTALL_INTO_DEV_ORG' | 'NO_ACCESS' | 'PACKAGING_DISABLED' | 'PACKAGING_NO_ACCESS' | 'PACKAGE_UNAVAILABLE' | 'UNINSTALL_IN_PROGRESS' | 'UNKNOWN_ERROR' | 'NAMESPACE_COLLISION';
     type SubscriberPackageVersion = {
         Id: string;
         SubscriberPackageId: string;
@@ -142,11 +157,11 @@ export declare namespace PackagingSObjects {
         AppExchangeLogoUrl: string;
         ReleaseNotesUrl: string;
         PostInstallUrl: string;
-        RemoteSiteSettings: unknown;
-        CspTrustedSites: unknown;
+        RemoteSiteSettings: SubscriberPackageRemoteSiteSettings;
+        CspTrustedSites: SubscriberPackageCspTrustedSites;
         Profiles: SubscriberPackageProfiles;
         Dependencies: SubscriberPackageDependencies;
-        InstallValidationStatus: string;
+        InstallValidationStatus: InstallValidationStatus;
     };
     type SubscriberPackageVersionUninstallRequest = {
         Id: string;
@@ -170,6 +185,19 @@ export declare namespace PackagingSObjects {
         SubscriberPackageVersionId: string;
         Status: string;
     };
+    type SubscriberPackageInstallError = {
+        message: string;
+    };
+    type SubscriberPackageInstallErrors = {
+        errors: SubscriberPackageInstallError[];
+    };
+    type SubscriberPackageProfileMapping = {
+        source: string;
+        target: string;
+    };
+    type SubscriberPackageProfileMappings = {
+        profileMappings: SubscriberPackageProfileMapping[];
+    };
     type PackageInstallRequest = {
         Id: string;
         IsDeleted: boolean;
@@ -179,16 +207,16 @@ export declare namespace PackagingSObjects {
         LastModifiedById: string;
         SystemModstamp: number;
         SubscriberPackageVersionKey: string;
-        NameConflictResolution: string;
-        SecurityType: string;
+        NameConflictResolution: 'Block' | 'RenameMetadata';
+        SecurityType: 'Custom' | 'Full' | 'None';
         PackageInstallSource: string;
-        ProfileMappings: unknown;
-        Password: string;
+        ProfileMappings: Nullable<SubscriberPackageProfileMappings>;
+        Password: Nullable<string>;
         EnableRss: boolean;
-        UpgradeType: string;
-        ApexCompileType: string;
-        Status: string;
-        Errors: any[];
+        UpgradeType: Nullable<'delete-only' | 'deprecate-only' | 'mixed-mode'>;
+        ApexCompileType: Nullable<'all' | 'package'>;
+        Status: 'ERROR' | 'IN_PROGRESS' | 'SUCCESS' | 'UNKNOWN';
+        Errors: Nullable<SubscriberPackageInstallErrors>;
     };
     type PackageUploadRequest = {
         Id: string;

package/lib/package/index.d.ts

@@ -1,4 +1,5 @@
 export * from './package';
+export * from './packageInstall';
 export * from './packageVersion';
 export * from './packageList';
 export * from './packageVersionCreateRequest';

package/lib/package/index.js

@@ -22,6 +22,7 @@ exports.deletePackage = exports.createPackage = exports.listPackageVersions = vo
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 __exportStar(require("./package"), exports);
+__exportStar(require("./packageInstall"), exports);
 __exportStar(require("./packageVersion"), exports);
 __exportStar(require("./packageList"), exports);
 __exportStar(require("./packageVersionCreateRequest"), exports);

package/lib/package/package.d.ts

@@ -1,5 +1,9 @@
-import { AsyncCreatable } from '@salesforce/kit';
-import { IPackage, PackageOptions } from '../interfaces';
+import { AsyncCreatable, Duration } from '@salesforce/kit';
+import { QueryResult } from 'jsforce';
+import { Optional } from '@salesforce/ts-types';
+import { IPackage, PackageOptions, PackagingSObjects } from '../interfaces';
+import { PackageInstallOptions, PackageInstallCreateRequest, PackageIdType } from '../interfaces/packagingInterfacesAndType';
+declare type PackageInstallRequest = PackagingSObjects.PackageInstallRequest;
 /**
  * Package class.
  *
@@ -8,12 +12,30 @@ import { IPackage, PackageOptions } from '../interfaces';
 export declare class Package extends AsyncCreatable<PackageOptions> implements IPackage {
     private options;
     constructor(options: PackageOptions);
+    /**
+     * Given a Salesforce ID for a package resource and the type of resource,
+     * ensures the ID is valid.
+     *
+     * Valid ID types and prefixes for packaging resources:
+     * 1. package ID (0Ho)
+     * 2. subscriber package version ID (04t)
+     * 3. package install request ID (0Hf)
+     * 4. package uninstall request ID (06y)
+     *
+     * @param id Salesforce ID for a specific package resource
+     * @param type The type of package ID
+     */
+    static validateId(id: string, type: PackageIdType): void;
     convert(): Promise<void>;
     create(): Promise<void>;
     delete(): Promise<void>;
-    install(): Promise<void>;
-    list(): Promise<void>;
+    install(pkgInstallCreateRequest: PackageInstallCreateRequest, options?: PackageInstallOptions): Promise<PackageInstallRequest>;
+    getInstallStatus(installRequestId: string): Promise<PackageInstallRequest>;
+    list(): Promise<QueryResult<PackagingSObjects.Package2>>;
     uninstall(): Promise<void>;
     update(): Promise<void>;
+    getExternalSites(subscriberPackageVersionId: string, installationKey?: string): Promise<Optional<string[]>>;
+    waitForPublish(subscriberPackageVersionId: string, timeout: number | Duration, installationKey?: string): Promise<void>;
     protected init(): Promise<void>;
 }
+export {};

package/lib/package/package.js

@@ -7,18 +7,50 @@ exports.Package = void 0;
  * Licensed under the BSD 3-Clause license.
  * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
+const core_1 = require("@salesforce/core");
 const kit_1 = require("@salesforce/kit");
+const packageList_1 = require("./packageList");
+const packageInstall_1 = require("./packageInstall");
+const packagePrefixes = {
+    PackageId: '0Ho',
+    SubscriberPackageVersionId: '04t',
+    PackageInstallRequestId: '0Hf',
+    PackageUninstallRequestId: '06y',
+};
+core_1.Messages.importMessagesDirectory(__dirname);
+const messages = core_1.Messages.loadMessages('@salesforce/packaging', 'package');
 /**
  * Package class.
  *
  * This class provides the base implementation for a package.
  */
 class Package extends kit_1.AsyncCreatable {
-    // @ts-ignore
     constructor(options) {
         super(options);
         this.options = options;
     }
+    /**
+     * Given a Salesforce ID for a package resource and the type of resource,
+     * ensures the ID is valid.
+     *
+     * Valid ID types and prefixes for packaging resources:
+     * 1. package ID (0Ho)
+     * 2. subscriber package version ID (04t)
+     * 3. package install request ID (0Hf)
+     * 4. package uninstall request ID (06y)
+     *
+     * @param id Salesforce ID for a specific package resource
+     * @param type The type of package ID
+     */
+    static validateId(id, type) {
+        const prefix = packagePrefixes[type];
+        if (!id.startsWith(prefix)) {
+            throw messages.createError('invalidPackageId', [type, id, prefix]);
+        }
+        if (!core_1.sfdc.validateSalesforceId(id)) {
+            throw messages.createError('invalidIdLength', [type, id]);
+        }
+    }
     convert() {
         return Promise.resolve(undefined);
     }
@@ -28,11 +60,14 @@ class Package extends kit_1.AsyncCreatable {
     delete() {
         return Promise.resolve(undefined);
     }
-    install() {
-        return Promise.resolve(undefined);
+    async install(pkgInstallCreateRequest, options) {
+        return (0, packageInstall_1.installPackage)(this.options.connection, pkgInstallCreateRequest, options);
+    }
+    async getInstallStatus(installRequestId) {
+        return (0, packageInstall_1.getStatus)(this.options.connection, installRequestId);
     }
     list() {
-        return Promise.resolve(undefined);
+        return (0, packageList_1.listPackages)(this.options.connection);
     }
     uninstall() {
         return Promise.resolve(undefined);
@@ -40,6 +75,12 @@ class Package extends kit_1.AsyncCreatable {
     update() {
         return Promise.resolve(undefined);
     }
+    async getExternalSites(subscriberPackageVersionId, installationKey) {
+        return (0, packageInstall_1.getExternalSites)(this.options.connection, subscriberPackageVersionId, installationKey);
+    }
+    async waitForPublish(subscriberPackageVersionId, timeout, installationKey) {
+        return (0, packageInstall_1.waitForPublish)(this.options.connection, subscriberPackageVersionId, timeout, installationKey);
+    }
     init() {
         return Promise.resolve(undefined);
     }

package/lib/package/packageInstall.d.ts

@@ -0,0 +1,18 @@
+import { Connection } from '@salesforce/core';
+import { Optional } from '@salesforce/ts-types';
+import { Duration } from '@salesforce/kit';
+import { PackagingSObjects } from '../interfaces';
+import { PackageInstallOptions, PackageInstallCreateRequest } from '../interfaces/packagingInterfacesAndType';
+import PackageInstallRequest = PackagingSObjects.PackageInstallRequest;
+export declare function installPackage(connection: Connection, pkgInstallCreateRequest: PackageInstallCreateRequest, options?: PackageInstallOptions): Promise<PackageInstallRequest>;
+/**
+ * Returns an array of RSS and CSP external sites for the package.
+ *
+ * @param connection The `Connection` object to the org.
+ * @param subscriberPackageVersionId The ID of the subscriber package version (begins with "04t")
+ * @param installationKey The installation key (if any) for the subscriber package version.
+ * @returns an array of RSS and CSP site URLs, or undefined if the package doesn't have any.
+ */
+export declare function getExternalSites(connection: Connection, subscriberPackageVersionId: string, installationKey?: string): Promise<Optional<string[]>>;
+export declare function getStatus(connection: Connection, installRequestId: string): Promise<PackageInstallRequest>;
+export declare function waitForPublish(connection: Connection, subscriberPackageVersionId: string, timeout: number | Duration, installationKey?: string): Promise<void>;

package/lib/package/packageInstall.js

@@ -0,0 +1,222 @@
+"use strict";
+/*
+ * Copyright (c) 2022, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForPublish = exports.getStatus = exports.getExternalSites = exports.installPackage = void 0;
+const core_1 = require("@salesforce/core");
+const ts_types_1 = require("@salesforce/ts-types");
+const kit_1 = require("@salesforce/kit");
+const packageUtils_1 = require("../utils/packageUtils");
+const constants_1 = require("../constants");
+core_1.Messages.importMessagesDirectory(__dirname);
+const installMsgs = core_1.Messages.loadMessages('@salesforce/packaging', 'package-install');
+let logger;
+const getLogger = () => {
+    if (!logger) {
+        logger = core_1.Logger.childFromRoot('installPackage');
+    }
+    return logger;
+};
+async function installPackage(connection, pkgInstallCreateRequest, options) {
+    const defaults = {
+        ApexCompileType: 'all',
+        EnableRss: false,
+        NameConflictResolution: 'Block',
+        PackageInstallSource: 'U',
+        SecurityType: 'none',
+        UpgradeType: 'mixed-mode',
+    };
+    const request = Object.assign({}, defaults, pkgInstallCreateRequest);
+    if (request.Password) {
+        request.Password = (0, packageUtils_1.escapeInstallationKey)(request.Password);
+    }
+    const pkgType = await (0, packageUtils_1.getPackageTypeBy04t)(request.SubscriberPackageVersionKey, connection, request.Password);
+    // Only unlocked packages can change the UpgradeType and ApexCompile options from the defaults.
+    if (pkgType !== 'Unlocked') {
+        if (request.UpgradeType !== defaults.UpgradeType) {
+            const msg = installMsgs.getMessage('upgradeTypeOnlyForUnlockedWarning');
+            await core_1.Lifecycle.getInstance().emit('PackageInstallRequest:warning', msg);
+            delete request.UpgradeType;
+        }
+        if (request.ApexCompileType !== defaults.ApexCompileType) {
+            const msg = installMsgs.getMessage('apexCompileOnlyForUnlockedWarning');
+            await core_1.Lifecycle.getInstance().emit('PackageInstallRequest:warning', msg);
+            delete request.ApexCompileType;
+        }
+    }
+    await core_1.Lifecycle.getInstance().emit('PackageInstallRequest:presend', request);
+    const result = await connection.tooling.create('PackageInstallRequest', request);
+    await core_1.Lifecycle.getInstance().emit('PackageInstallRequest:postsend', result);
+    const packageInstallRequestId = result.id;
+    if (!packageInstallRequestId) {
+        throw installMsgs.createError('packageInstallRequestError', [
+            request.SubscriberPackageVersionKey,
+            result.errors.toString(),
+        ]);
+    }
+    if (options?.pollingTimeout == null) {
+        return getStatus(connection, packageInstallRequestId);
+    }
+    else {
+        return pollStatus(connection, packageInstallRequestId, options);
+    }
+}
+exports.installPackage = installPackage;
+/**
+ * Returns an array of RSS and CSP external sites for the package.
+ *
+ * @param connection The `Connection` object to the org.
+ * @param subscriberPackageVersionId The ID of the subscriber package version (begins with "04t")
+ * @param installationKey The installation key (if any) for the subscriber package version.
+ * @returns an array of RSS and CSP site URLs, or undefined if the package doesn't have any.
+ */
+async function getExternalSites(connection, subscriberPackageVersionId, installationKey) {
+    const installKey = (0, packageUtils_1.escapeInstallationKey)(installationKey);
+    const queryNoKey = `SELECT RemoteSiteSettings, CspTrustedSites FROM SubscriberPackageVersion WHERE Id ='${subscriberPackageVersionId}'`;
+    const queryWithKey = `SELECT RemoteSiteSettings, CspTrustedSites FROM SubscriberPackageVersion WHERE Id ='${subscriberPackageVersionId}' AND InstallationKey ='${installKey}'`;
+    let queryResult;
+    try {
+        getLogger().debug(`Checking package: [${subscriberPackageVersionId}] for external sites`);
+        queryResult = await connection.tooling.query(queryWithKey);
+    }
+    catch (e) {
+        // First check for Implementation Restriction error that is enforced in 214, before it was possible to query
+        // against InstallationKey, otherwise surface the error.
+        if (e instanceof Error && (0, packageUtils_1.isErrorFromSPVQueryRestriction)(e)) {
+            queryResult = await connection.tooling.query(queryNoKey);
+        }
+        else {
+            throw e;
+        }
+    }
+    if (queryResult?.records?.length > 0) {
+        const record = queryResult.records[0];
+        const rssUrls = record.RemoteSiteSettings.settings.map((rss) => rss.url);
+        const cspUrls = record.CspTrustedSites.settings.map((csp) => csp.endpointUrl);
+        const sites = [...rssUrls, ...cspUrls];
+        if (sites.length) {
+            return sites;
+        }
+    }
+}
+exports.getExternalSites = getExternalSites;
+async function getStatus(connection, installRequestId) {
+    const result = await connection.tooling.retrieve('PackageInstallRequest', installRequestId);
+    return result;
+}
+exports.getStatus = getStatus;
+// internal
+async function pollStatus(connection, installRequestId, options) {
+    let packageInstallRequest;
+    const { pollingFrequency, pollingTimeout } = options;
+    let frequency;
+    if (pollingFrequency != null) {
+        frequency = (0, ts_types_1.isNumber)(pollingFrequency) ? kit_1.Duration.milliseconds(pollingFrequency) : pollingFrequency;
+    }
+    else {
+        frequency = kit_1.Duration.milliseconds(constants_1.consts.PACKAGE_INSTALL_POLL_FREQUENCY);
+    }
+    let timeout;
+    if (pollingTimeout != null) {
+        timeout = (0, ts_types_1.isNumber)(pollingTimeout) ? kit_1.Duration.minutes(pollingTimeout) : pollingTimeout;
+    }
+    else {
+        timeout = kit_1.Duration.minutes(constants_1.consts.PACKAGE_INSTALL_POLL_TIMEOUT);
+    }
+    const pollingOptions = {
+        frequency,
+        timeout,
+        poll: async () => {
+            packageInstallRequest = await getStatus(connection, installRequestId);
+            getLogger().debug(installMsgs.getMessage('packageInstallPolling', [packageInstallRequest?.Status]));
+            await core_1.Lifecycle.getInstance().emit('PackageInstallRequest:status', packageInstallRequest);
+            if (['SUCCESS', 'ERROR'].includes(packageInstallRequest?.Status)) {
+                return { completed: true, payload: packageInstallRequest };
+            }
+            return { completed: false };
+        },
+    };
+    const pollingClient = await core_1.PollingClient.create(pollingOptions);
+    try {
+        getLogger().debug(`Polling for PackageInstallRequest status. Package ID = ${installRequestId}`);
+        getLogger().debug(`Polling frequency (ms): ${pollingOptions.frequency.milliseconds}`);
+        getLogger().debug(`Polling timeout (min): ${pollingOptions.timeout.minutes}`);
+        await pollingClient.subscribe();
+        return packageInstallRequest;
+    }
+    catch (e) {
+        const errMsg = e instanceof Error ? e.message : (0, ts_types_1.isString)(e) ? e : 'polling timed out';
+        const error = new core_1.SfError(errMsg, 'PackageInstallTimeout');
+        error.setData(packageInstallRequest);
+        if (error.stack && e.stack) {
+            // add the original stack to this new error
+            error.stack += `\nDUE TO:\n${e.stack}`;
+        }
+        throw error;
+    }
+}
+async function waitForPublish(connection, subscriberPackageVersionId, timeout, installationKey) {
+    let queryResult;
+    const pollingOptions = {
+        frequency: kit_1.Duration.milliseconds(constants_1.consts.PACKAGE_INSTALL_POLL_FREQUENCY),
+        timeout: (0, ts_types_1.isNumber)(timeout) ? kit_1.Duration.minutes(timeout) : timeout,
+        poll: async () => {
+            const QUERY_NO_KEY = `SELECT Id, SubscriberPackageId, InstallValidationStatus FROM SubscriberPackageVersion WHERE Id ='${subscriberPackageVersionId}'`;
+            try {
+                const escapedInstallationKey = installationKey ? (0, packageUtils_1.escapeInstallationKey)(installationKey) : null;
+                const queryWithKey = `${QUERY_NO_KEY} AND InstallationKey ='${escapedInstallationKey}'`;
+                queryResult = await connection.tooling.query(queryWithKey);
+            }
+            catch (e) {
+                // Check first for Implementation Restriction error that is enforced in 214, before it was possible to query
+                // against InstallationKey, otherwise surface the error.
+                if (e instanceof Error && (0, packageUtils_1.isErrorFromSPVQueryRestriction)(e)) {
+                    queryResult = await connection.tooling.query(QUERY_NO_KEY);
+                }
+                else {
+                    if (e instanceof Error && !(0, packageUtils_1.isErrorPackageNotAvailable)(e)) {
+                        throw e;
+                    }
+                }
+            }
+            // Continue retrying if there is no record
+            // or for an InstallValidationStatus of PACKAGE_UNAVAILABLE (replication to the subscriber's instance has not completed)
+            // or for an InstallValidationStatus of UNINSTALL_IN_PROGRESS
+            let installValidationStatus;
+            if (queryResult?.records?.length) {
+                installValidationStatus = queryResult.records[0].InstallValidationStatus;
+                await core_1.Lifecycle.getInstance().emit('SubscriberPackageVersion:status', installValidationStatus);
+                if (!['PACKAGE_UNAVAILABLE', 'UNINSTALL_IN_PROGRESS'].includes(installValidationStatus)) {
+                    return { completed: true, payload: queryResult };
+                }
+            }
+            const tokens = installValidationStatus ? [` Status = ${installValidationStatus}`] : [];
+            getLogger().debug(installMsgs.getMessage('publishWaitProgress', tokens));
+            await core_1.Lifecycle.getInstance().emit('SubscriberPackageVersion:status', installValidationStatus);
+            return { completed: false, payload: queryResult };
+        },
+    };
+    const pollingClient = await core_1.PollingClient.create(pollingOptions);
+    try {
+        getLogger().debug(`Polling for package availability in org. Package ID = ${subscriberPackageVersionId}`);
+        getLogger().debug(`Polling frequency (ms): ${pollingOptions.frequency.milliseconds}`);
+        getLogger().debug(`Polling timeout (min): ${pollingOptions.timeout.minutes}`);
+        await pollingClient.subscribe();
+    }
+    catch (e) {
+        // if polling timed out
+        const error = installMsgs.createError('subscriberPackageVersionNotPublished');
+        error.setData(queryResult);
+        if (error.stack && e.stack) {
+            // append the original stack to this new error
+            error.stack += `\nDUE TO:\n${e.stack}`;
+        }
+        throw error;
+    }
+}
+exports.waitForPublish = waitForPublish;
+//# sourceMappingURL=packageInstall.js.map

package/lib/utils/packageUtils.d.ts

@@ -1,6 +1,6 @@
 import { Connection, NamedPackageDir, PackageDir, SfdcUrl, SfError, SfProject } from '@salesforce/core';
 import { Duration } from '@salesforce/kit';
-import { Many } from '@salesforce/ts-types';
+import { Many, Nullable } from '@salesforce/ts-types';
 import { SaveError } from 'jsforce';
 import { PackagingSObjects, PackageVersionCreateRequestResult, PackageVersionCreateOptions } from '../interfaces';
 export declare const VERSION_NUMBER_SEP = ".";
@@ -39,6 +39,7 @@ export declare function applyErrorAction(err: Error): Error;
  * @param connection For tooling query
  */
 export declare function getPackageVersionId(versionId: string, connection: Connection): Promise<string>;
+export declare function escapeInstallationKey(key?: string): Nullable<string>;
 /**
  * Given 0Ho the package type type (Managed, Unlocked, Locked(deprecated?))
  *
@@ -55,7 +56,7 @@ export declare function getPackageType(packageId: string, connection: Connection
  * @param installKey For tooling query, if an installation key is applicable to the package version it must be passed in the queries
  * @throws Error with message when package2 cannot be found
  */
-export declare function getPackageTypeBy04t(packageVersionId: string, connection: Connection, installKey: string): Promise<string>;
+export declare function getPackageTypeBy04t(packageVersionId: string, connection: Connection, installKey?: string): Promise<string>;
 /**
  * Given a package version ID (05i) or subscriber package version ID (04t), return the subscriber package version ID (04t)
  *

package/lib/utils/packageUtils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveCanonicalPackageProperty = exports.combineSaveErrors = exports.formatDate = exports.getSoqlWhereClauseMaxLength = exports.pollForStatusWithInterval = exports.findOrCreatePackage = exports.getPackageAliasesFromId = exports.convertCamelCaseStringToSentence = exports.getPackageIdFromAlias = exports.getConfigPackageDirectory = exports.getConfigPackageDirectories = exports.getPackageVersionNumber = exports.concatVersion = exports.getAncestorIdHighestRelease = exports.validateAncestorId = exports.getAncestorId = exports.getInClauseItemsCount = exports.queryWithInConditionChunking = exports.getPackageVersionStrings = exports.getHasMetadataRemoved = exports.getContainerOptions = exports.getSubscriberPackageVersionId = exports.getPackageTypeBy04t = exports.getPackageType = exports.getPackageVersionId = exports.applyErrorAction = exports.massageErrorMessage = exports.isErrorPackageNotAvailable = exports.isErrorFromSPVQueryRestriction = exports.validUrl = exports.validatePatchVersion = exports.validateVersionNumber = exports.validateIdNoThrow = exports.validateId = exports.BY_LABEL = exports.BY_PREFIX = exports.DEFAULT_PACKAGE_DIR = exports.POLL_INTERVAL_SECONDS = exports.SOQL_WHERE_CLAUSE_MAX_LENGTH = exports.INSTALL_URL_BASE = exports.VERSION_NUMBER_SEP = void 0;
+exports.resolveCanonicalPackageProperty = exports.combineSaveErrors = exports.formatDate = exports.getSoqlWhereClauseMaxLength = exports.pollForStatusWithInterval = exports.findOrCreatePackage = exports.getPackageAliasesFromId = exports.convertCamelCaseStringToSentence = exports.getPackageIdFromAlias = exports.getConfigPackageDirectory = exports.getConfigPackageDirectories = exports.getPackageVersionNumber = exports.concatVersion = exports.getAncestorIdHighestRelease = exports.validateAncestorId = exports.getAncestorId = exports.getInClauseItemsCount = exports.queryWithInConditionChunking = exports.getPackageVersionStrings = exports.getHasMetadataRemoved = exports.getContainerOptions = exports.getSubscriberPackageVersionId = exports.getPackageTypeBy04t = exports.getPackageType = exports.escapeInstallationKey = exports.getPackageVersionId = exports.applyErrorAction = exports.massageErrorMessage = exports.isErrorPackageNotAvailable = exports.isErrorFromSPVQueryRestriction = exports.validUrl = exports.validatePatchVersion = exports.validateVersionNumber = exports.validateIdNoThrow = exports.validateId = exports.BY_LABEL = exports.BY_PREFIX = exports.DEFAULT_PACKAGE_DIR = exports.POLL_INTERVAL_SECONDS = exports.SOQL_WHERE_CLAUSE_MAX_LENGTH = exports.INSTALL_URL_BASE = exports.VERSION_NUMBER_SEP = void 0;
 /*
  * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
@@ -211,6 +211,10 @@ async function getPackageVersionId(versionId, connection) {
     });
 }
 exports.getPackageVersionId = getPackageVersionId;
+function escapeInstallationKey(key) {
+    return key ? key.replace(/\\/g, '\\\\').replace(/'/g, "\\'") : null;
+}
+exports.escapeInstallationKey = escapeInstallationKey;
 /**
  * Given 0Ho the package type type (Managed, Unlocked, Locked(deprecated?))
  *

package/lib/utils/srcDevUtils.d.ts

@@ -5,8 +5,7 @@
  *
  * @param dir to zip
  * @param zipfile
- * @param options
  */
-export declare function zipDir(dir: string, zipfile: string, options?: {}): Promise<void>;
+export declare function zipDir(dir: string, zipfile: string): Promise<void>;
 export declare function getElapsedTime(timer: [number, number]): string;
 export declare function copyDir(src: string, dest: string): void;

package/lib/utils/srcDevUtils.js

@@ -22,9 +22,8 @@ const pipeline = (0, util_1.promisify)(stream_1.pipeline);
  *
  * @param dir to zip
  * @param zipfile
- * @param options
  */
-async function zipDir(dir, zipfile, options = {}) {
+async function zipDir(dir, zipfile) {
     const logger = core_1.Logger.childFromRoot('srcDevUtils#zipDir');
     const timer = process.hrtime();
     const globbyResult = await globby('**/*', { expandDirectories: true, cwd: dir });

package/messages/package-install.md

@@ -0,0 +1,28 @@
+# upgradeTypeOnlyForUnlockedWarning
+
+WARNING: We ignored the upgradetype parameter when installing this package version. The upgradetype parameter is available only for unlocked package installations. Managed package upgrades always default to using the Mixed upgrade type.
+
+# apexCompileOnlyForUnlockedWarning
+
+WARNING: We ignored the apexcompile parameter when installing this package version. The apexcompile parameter is available only for installations of unlocked packages.
+
+# packageInstallPolling
+
+Waiting for the package install request to complete. Status = %s
+
+# packageInstallRequestError
+
+Failed to create PackageInstallRequest for: %s
+Due to: %s
+
+# publishWaitProgress
+
+Waiting for the Subscriber Package Version ID to be published to the target org.%s
+
+# subscriberPackageVersionNotPublished
+
+The subscriber package version is not fully available.
+
+# subscriberPackageVersionNotPublished.actions
+
+If this is a recently created package version, try again in a few minutes or contact the package publisher.

package/messages/package.md

@@ -0,0 +1,7 @@
+# invalidPackageId
+
+The %s: [%s] is invalid. It must start with "%s".
+
+# invalidIdLength
+
+The %s: [%s] is invalid. It must be either 15 or 18 characters.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/packaging",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "packing libraries to Salesforce packaging platform",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -35,8 +35,8 @@
     "!lib/**/*.map"
   ],
   "dependencies": {
-    "@salesforce/core": "^3.23.7",
-    "@salesforce/kit": "^1.5.42",
+    "@salesforce/core": "^3.24.0",
+    "@salesforce/kit": "^1.5.44",
     "@salesforce/schemas": "^1.2.0",
     "@salesforce/source-deploy-retrieve": "^6.2.0",
     "@salesforce/ts-types": "^1.5.20",