@salesforce/packaging 1.5.6 → 1.6.0

package/lib/interfaces/packagingInterfacesAndType.d.ts

@@ -3,6 +3,7 @@ import { Connection, NamedPackageDir, SfProject } from '@salesforce/core';
 import { SaveResult } from 'jsforce';
 import { Attributes } from 'graphology-types';
 import { Optional } from '@salesforce/ts-types';
+import { ConvertResult } from '@salesforce/source-deploy-retrieve';
 import { PackageProfileApi } from '../package/packageProfileApi';
 import { PackageAncestryNode } from '../package/packageAncestry';
 import { PackagingSObjects } from './packagingSObjects';
@@ -170,6 +171,11 @@ export type PackageVersionCreateRequestOptions = {
     branch?: string;
     skipancestorcheck?: boolean;
 };
+export type PackageVersionMetadataDownloadOptions = {
+    subscriberPackageVersionId: string;
+    destinationFolder?: string;
+};
+export type PackageVersionMetadataDownloadResult = ConvertResult;
 export type PackageInstallOptions = {
     /**
      * The frequency to poll the org for package publish status. If providing a number

package/lib/interfaces/packagingSObjects.d.ts

@@ -297,5 +297,6 @@ export declare namespace PackagingSObjects {
         PatchVersion: number;
         BuildNumber: number;
         IsDeprecated: boolean;
+        MetadataZip?: string;
     };
 }

package/lib/package/package.d.ts

@@ -1,5 +1,5 @@
 import { Connection, SfProject } from '@salesforce/core';
-import { ConvertPackageOptions, PackageCreateOptions, PackageOptions, PackageSaveResult, PackageType, PackageUpdateOptions, PackageVersionCreateRequestResult, PackageVersionListOptions, PackageVersionListResult, PackagingSObjects } from '../interfaces';
+import { ConvertPackageOptions, PackageCreateOptions, PackageOptions, PackageSaveResult, PackageType, PackageUpdateOptions, PackageVersionCreateRequestResult, PackageVersionListOptions, PackageVersionListResult, PackagingSObjects, PackageVersionMetadataDownloadOptions, PackageVersionMetadataDownloadResult } from '../interfaces';
 import { PackageAncestry } from './packageAncestry';
 export declare const Package2Fields: string[];
 /**
@@ -69,6 +69,15 @@ export declare class Package {
      * @param project
      */
     static convert(pkgId: string, connection: Connection, options: ConvertPackageOptions, project?: SfProject): Promise<PackageVersionCreateRequestResult>;
+    /**
+     * Download the metadata files for a previously published package version, convert them to source format, and put them into a new project folder within the sfdx project.
+     *
+     * @param project
+     * @param options {@link PackageVersionMetadataDownloadOptions}
+     * @param connection
+     * @returns
+     */
+    static downloadPackageVersionMetadata(project: SfProject, options: PackageVersionMetadataDownloadOptions, connection: Connection): Promise<PackageVersionMetadataDownloadResult>;
     private static getPackage2Fields;
     /**
      * Returns the package ID of the package.

package/lib/package/package.js

@@ -7,7 +7,10 @@ exports.Package = exports.Package2Fields = 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 path = require("path");
+const fs = require("fs");
 const core_1 = require("@salesforce/core");
+const source_deploy_retrieve_1 = require("@salesforce/source-deploy-retrieve");
 const packageUtils_1 = require("../utils/packageUtils");
 const packageCreate_1 = require("./packageCreate");
 const packageConvert_1 = require("./packageConvert");
@@ -150,6 +153,53 @@ class Package {
     static async convert(pkgId, connection, options, project) {
         return (0, packageConvert_1.convertPackage)(pkgId, connection, options, project);
     }
+    /**
+     * Download the metadata files for a previously published package version, convert them to source format, and put them into a new project folder within the sfdx project.
+     *
+     * @param project
+     * @param options {@link PackageVersionMetadataDownloadOptions}
+     * @param connection
+     * @returns
+     */
+    static async downloadPackageVersionMetadata(project, options, connection) {
+        // Validate the destination path is suitable to extract package version metadata (must be new or empty)
+        const destinationFolder = options.destinationFolder ?? 'force-app';
+        if (path.isAbsolute(destinationFolder)) {
+            throw messages.createError('sourcesDownloadDirectoryMustBeRelative');
+        }
+        const destinationPath = path.join(project.getPath(), destinationFolder);
+        if (!fs.existsSync(destinationPath)) {
+            fs.mkdirSync(destinationPath, { recursive: true });
+        }
+        if (!(0, packageUtils_1.isPackageDirectoryEffectivelyEmpty)(destinationPath)) {
+            throw messages.createError('sourcesDownloadDirectoryNotEmpty');
+        }
+        // Get the MetadataZip URL from the MetadataPackageVersion record
+        const { subscriberPackageVersionId } = options;
+        const versionInfo = (await connection.tooling
+            .sobject('MetadataPackageVersion')
+            .retrieve(subscriberPackageVersionId));
+        if (!versionInfo.MetadataZip) {
+            throw messages.createError('unableToAccessMetadataZip');
+        }
+        const responseBase64 = await connection.tooling.request(versionInfo.MetadataZip, {
+            encoding: 'base64',
+        });
+        const buffer = Buffer.from(responseBase64, 'base64');
+        const converter = new source_deploy_retrieve_1.MetadataConverter();
+        const tree = await source_deploy_retrieve_1.ZipTreeContainer.create(buffer);
+        const zipComponents = source_deploy_retrieve_1.ComponentSet.fromSource({
+            fsPaths: ['.'],
+            tree,
+        })
+            .getSourceComponents()
+            .toArray();
+        return converter.convert(zipComponents, 'source', {
+            type: 'directory',
+            outputDirectory: destinationPath,
+            genUniqueDir: false,
+        });
+    }
     static getPackage2Fields(connection) {
         const apiVersion = connection.getApiVersion();
         return exports.Package2Fields.filter((field) => (apiVersion >= '59.0' ? true : field !== 'AppAnalyticsEnabled'));

package/lib/package/packageVersionCreate.js

@@ -475,7 +475,15 @@ class PackageVersionCreate {
             throw error;
         }
         const request = await this.createPackageVersionCreateRequestFromOptions();
-        const createResult = await this.connection.tooling.create('Package2VersionCreateRequest', request);
+        const options = {
+            multipartFileFields: {
+                VersionInfo: {
+                    contentType: 'application/zip',
+                    filename: 'package-version-info.zip',
+                },
+            },
+        };
+        const createResult = await this.connection.tooling.create('Package2VersionCreateRequest', request, options);
         if (!createResult.success) {
             const errStr = createResult.errors?.join(', ') ?? createResult.errors;
             const id = createResult.id ?? '';

package/lib/utils/packageUtils.d.ts

@@ -98,3 +98,13 @@ export declare function zipDir(dir: string, zipfile: string): Promise<void>;
 export declare function copyDir(src: string, dest: string): void;
 export declare function copyDescriptorProperties(packageDescriptorJson: PackageDescriptorJson, definitionFileJson: ScratchOrgInfo): PackageDescriptorJson;
 export declare function replaceIfEmpty<T>(value: T, replacement: T): T;
+/**
+ * Brand new SFDX projects contain a force-app directory tree contiaining empty folders
+ * and a few .eslint.json files. We still want to consider such a directory tree
+ * as 'empty' for the sake of operations like downloading package version metadata.
+ *
+ * @param directory The absolute path to a directory
+ * @returns true if the directory contains nothing except empty directories or
+ * directories containing only an .eslint.json file.
+ */
+export declare function isPackageDirectoryEffectivelyEmpty(directory: string): boolean;

package/lib/utils/packageUtils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.replaceIfEmpty = exports.copyDescriptorProperties = exports.copyDir = exports.zipDir = exports.numberToDuration = exports.combineSaveErrors = exports.generatePackageAliasEntry = exports.getPackageVersionNumber = exports.getPackageVersionStrings = exports.getContainerOptions = exports.escapeInstallationKey = exports.getPackageVersionId = exports.massageErrorMessage = exports.applyErrorAction = exports.validateIdNoThrow = exports.validateId = exports.uniqid = exports.BY_LABEL = exports.DEFAULT_PACKAGE_DIR = exports.POLL_INTERVAL_SECONDS = exports.INSTALL_URL_BASE = exports.VERSION_NUMBER_SEP = void 0;
+exports.isPackageDirectoryEffectivelyEmpty = exports.replaceIfEmpty = exports.copyDescriptorProperties = exports.copyDir = exports.zipDir = exports.numberToDuration = exports.combineSaveErrors = exports.generatePackageAliasEntry = exports.getPackageVersionNumber = exports.getPackageVersionStrings = exports.getContainerOptions = exports.escapeInstallationKey = exports.getPackageVersionId = exports.massageErrorMessage = exports.applyErrorAction = exports.validateIdNoThrow = exports.validateId = exports.uniqid = exports.BY_LABEL = exports.DEFAULT_PACKAGE_DIR = exports.POLL_INTERVAL_SECONDS = exports.INSTALL_URL_BASE = exports.VERSION_NUMBER_SEP = void 0;
 /*
  * Copyright (c) 2022, salesforce.com, inc.
  * All rights reserved.
@@ -407,4 +407,23 @@ function replaceIfEmpty(value, replacement) {
     return !(0, kit_1.isEmpty)(value) ? value : replacement;
 }
 exports.replaceIfEmpty = replaceIfEmpty;
+/**
+ * Brand new SFDX projects contain a force-app directory tree contiaining empty folders
+ * and a few .eslint.json files. We still want to consider such a directory tree
+ * as 'empty' for the sake of operations like downloading package version metadata.
+ *
+ * @param directory The absolute path to a directory
+ * @returns true if the directory contains nothing except empty directories or
+ * directories containing only an .eslint.json file.
+ */
+function isPackageDirectoryEffectivelyEmpty(directory) {
+    if (!fs.lstatSync(directory).isDirectory()) {
+        return false;
+    }
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+    return entries.every((entry) => entry.isDirectory()
+        ? isPackageDirectoryEffectivelyEmpty((0, path_1.join)(directory, entry.name))
+        : entry.name === '.eslint.json');
+}
+exports.isPackageDirectoryEffectivelyEmpty = isPackageDirectoryEffectivelyEmpty;
 //# sourceMappingURL=packageUtils.js.map

package/messages/package.md

@@ -25,3 +25,21 @@ A package with id %s was not found.
 # appAnalyticsEnabledApiPriorTo59Error
 
 Enabling App Analytics is only possible with API version 59.0 or higher.
+
+# sourcesDownloadDirectoryNotEmpty
+
+Can’t retrieve package version metadata. The specified directory isn’t empty. Empty the directory, or create a new one and try again.
+
+# sourcesDownloadDirectoryMustBeRelative
+
+Can’t retrieve package version metadata. The specified directory must be relative to your Salesforce DX project directory, and not an absolute path.
+
+# unableToAccessMetadataZip
+
+Can’t retrieve package version metadata. Ensure that you’re using API version 59.0 or higher, and that you have the user permissions needed to access fields on the MetadataPackageVersion object.
+
+# errorDownloadingMetadataZip
+
+Can’t retrieve package version metadata.
+
+An error occurred downloading the metadata: %s

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/packaging",
-  "version": "1.5.6",
+  "version": "1.6.0",
   "description": "Packaging library for the Salesforce packaging platform",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",
@@ -42,7 +42,7 @@
     "@salesforce/core": "^3.36.1",
     "@salesforce/kit": "^1.9.2",
     "@salesforce/schemas": "^1.5.1",
-    "@salesforce/source-deploy-retrieve": "^8.0.7",
+    "@salesforce/source-deploy-retrieve": "^8.5.1",
     "@salesforce/ts-types": "^1.7.3",
     "@xmldom/xmldom": "^0.8.7",
     "debug": "^4.3.4",
@@ -51,14 +51,14 @@
     "graphology-traversal": "^0.3.1",
     "graphology-types": "^0.24.7",
     "js2xmlparser": "^4.0.2",
-    "jsforce": "2.0.0-beta.23",
+    "jsforce": "^2.0.0-beta.23",
     "jszip": "^3.10.1",
     "mkdirp": "1.0.4",
     "ts-retry-promise": "^0.7.0",
     "xml2js": "^0.5.0"
   },
   "devDependencies": {
-    "@salesforce/cli-plugins-testkit": "^3.3.6",
+    "@salesforce/cli-plugins-testkit": "^3.4.0",
     "@salesforce/dev-config": "^3.1.0",
     "@salesforce/dev-scripts": "^4.3.1",
     "@salesforce/prettier-config": "^0.0.2",
@@ -67,8 +67,8 @@
     "@types/globby": "^9.1.0",
     "@types/jszip": "^3.4.1",
     "@types/xml2js": "^0.4.11",
-    "@typescript-eslint/eslint-plugin": "^5.59.2",
-    "@typescript-eslint/parser": "^5.59.5",
+    "@typescript-eslint/eslint-plugin": "^5.59.6",
+    "@typescript-eslint/parser": "^5.59.6",
     "chai": "^4.3.7",
     "commitizen": "^4.2.6",
     "eslint": "^8.40.0",