@salesforce/packaging 1.0.6 → 1.0.8

package/README.md

@@ -1,7 +1,5 @@
 # Salesforce Packaging
 
-> :warning: **This module is under heavy development, please do not use in production.**
-
 [![NPM](https://img.shields.io/npm/v/@salesforce/packaging.svg?label=@salesforce/packaging)](https://www.npmjs.com/package/@salesforce/packaging) [![Downloads/week](https://img.shields.io/npm/dw/@salesforce/packaging.svg)](https://npmjs.org/package/@salesforce/packaging) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/forcedotcom/packaging/main/LICENSE.txt)
 
 ## Description
@@ -12,12 +10,12 @@ A TypeScript library for packaging metadata in your Salesforce project. This lib
 
 There are 4 main classes to use from this library:
 
-1. `Package1Version` - Work with 1st generation package versions.
-1. `Package` - Work with 2nd generation packages.
-1. `PackageVersion` - Work with 2nd generation package versions.
-1. `SubscriberPackageVersion` - Work with 2nd generation subscriber package versions.
+1. [Package1Version](https://forcedotcom.github.io/packaging/classes/package1_package1Version.Package1Version.html) - Work with 1st generation package versions.
+1. [Package](https://forcedotcom.github.io/packaging/classes/package_package.Package.html) - Work with 2nd generation packages.
+1. [PackageVersion](https://forcedotcom.github.io/packaging/classes/package_packageVersion.PackageVersion.html) - Work with 2nd generation package versions.
+1. [SubscriberPackageVersion](https://forcedotcom.github.io/packaging/classes/package_subscriberPackageVersion.SubscriberPackageVersion.html) - Work with 2nd generation subscriber package versions.
 
-Please see the [API Documentation](https://forcedotcom.github.io/packaging/) for details.
+Please reference the [API Documentation](https://forcedotcom.github.io/packaging/) for complete details of code and types.
 
 ## Contributing
 

package/lib/package/package.d.ts

@@ -3,10 +3,22 @@ import { ConvertPackageOptions, PackageCreateOptions, PackageOptions, PackageSav
 import { PackageAncestry } from './packageAncestry';
 export declare const Package2Fields: string[];
 /**
- * Package class.
+ * Provides the ability to list, create, update, delete, convert, and get version
+ * ancestry for a 2nd generation package.
  *
- * This class provides the base implementation for a package.
- * To create a new instance of a package, use the static async Package.create({connection, project, packageOrAliasId}) method.
+ * **Examples**
+ *
+ * Create a new instance and get the ID (0Ho):
+ *
+ * `const id = new Package({connection, project, packageOrAliasId}).getId();`
+ *
+ * Create a new package in the org:
+ *
+ * `const myPkg = await Package.create(connection, project, options);`
+ *
+ * List all packages in the org:
+ *
+ * `const pkgList = await Package.list(connection);`
  */
 export declare class Package {
     private options;

package/lib/package/package.js

@@ -41,10 +41,22 @@ exports.Package2Fields = [
     'PackageErrorUsername',
 ];
 /**
- * Package class.
+ * Provides the ability to list, create, update, delete, convert, and get version
+ * ancestry for a 2nd generation package.
  *
- * This class provides the base implementation for a package.
- * To create a new instance of a package, use the static async Package.create({connection, project, packageOrAliasId}) method.
+ * **Examples**
+ *
+ * Create a new instance and get the ID (0Ho):
+ *
+ * `const id = new Package({connection, project, packageOrAliasId}).getId();`
+ *
+ * Create a new package in the org:
+ *
+ * `const myPkg = await Package.create(connection, project, options);`
+ *
+ * List all packages in the org:
+ *
+ * `const pkgList = await Package.list(connection);`
  */
 class Package {
     constructor(options) {

package/lib/package/packageVersion.d.ts

@@ -3,6 +3,24 @@ import { Duration } from '@salesforce/kit';
 import { PackageSaveResult, PackageType, PackageVersionCreateOptions, PackageVersionCreateRequestQueryOptions, PackageVersionCreateRequestResult, PackageVersionOptions, PackageVersionReportResult, PackageVersionUpdateOptions, PackagingSObjects } from '../interfaces';
 declare type Package2Version = PackagingSObjects.Package2Version;
 export declare const Package2VersionFields: string[];
+/**
+ * Provides the ability to create, update, delete, and promote 2nd
+ * generation package versions.
+ *
+ * **Examples**
+ *
+ * Create a new instance and get the ID (05i):
+ *
+ * `const id = new PackageVersion({connection, project, idOrAlias}).getId();`
+ *
+ * Create a new package version in the org:
+ *
+ * `const myPkgVersion = await PackageVersion.create(options, pollingOptions);`
+ *
+ * Promote a package version:
+ *
+ * `new PackageVersion({connection, project, idOrAlias}).promote();`
+ */
 export declare class PackageVersion {
     private options;
     private readonly project;
@@ -125,16 +143,6 @@ export declare class PackageVersion {
      */
     promote(): Promise<PackageSaveResult>;
     update(options: PackageVersionUpdateOptions): Promise<PackageSaveResult>;
-    /**
-     * Creates a new package version.
-     *
-     * @param options
-     * @param polling frequency and timeout Durations to be used in polling
-     */
-    create(options: PackageVersionCreateOptions, polling?: {
-        frequency: Duration;
-        timeout: Duration;
-    }): Promise<Partial<PackageVersionCreateRequestResult>>;
     private updateDeprecation;
     private updateProjectWithPackageVersion;
     private resolveId;

package/lib/package/packageVersion.js

@@ -50,6 +50,24 @@ exports.Package2VersionFields = [
     'BuildDurationInSeconds',
     'HasMetadataRemoved',
 ];
+/**
+ * Provides the ability to create, update, delete, and promote 2nd
+ * generation package versions.
+ *
+ * **Examples**
+ *
+ * Create a new instance and get the ID (05i):
+ *
+ * `const id = new PackageVersion({connection, project, idOrAlias}).getId();`
+ *
+ * Create a new package version in the org:
+ *
+ * `const myPkgVersion = await PackageVersion.create(options, pollingOptions);`
+ *
+ * Promote a package version:
+ *
+ * `new PackageVersion({connection, project, idOrAlias}).promote();`
+ */
 class PackageVersion {
     constructor(options) {
         this.options = options;
@@ -407,27 +425,6 @@ class PackageVersion {
         result.id = await this.getSubscriberId();
         return result;
     }
-    /**
-     * Creates a new package version.
-     *
-     * @param options
-     * @param polling frequency and timeout Durations to be used in polling
-     */
-    async create(options, polling = {
-        frequency: kit_1.Duration.seconds(0),
-        timeout: kit_1.Duration.seconds(0),
-    }) {
-        const pvc = new packageVersionCreate_1.PackageVersionCreate({ ...options, ...this.options });
-        const createResult = await pvc.createPackageVersion();
-        if (polling.timeout?.milliseconds > 0) {
-            return PackageVersion.waitForCreateVersion(createResult.Id, this.project, this.connection, polling).catch((err) => {
-                // TODO
-                // until package2 is GA, wrap perm-based errors w/ 'contact sfdc' action (REMOVE once package2 is GA'd)
-                throw (0, packageUtils_1.applyErrorAction)((0, packageUtils_1.massageErrorMessage)(err));
-            });
-        }
-        return createResult;
-    }
     async updateDeprecation(isDeprecated) {
         const id = await this.getId();
         // setup the request
@@ -446,7 +443,11 @@ class PackageVersion {
         if (!process.env.SFDX_PROJECT_AUTOUPDATE_DISABLE_FOR_PACKAGE_VERSION_CREATE) {
             // get the newly created package version from the server
             const versionResult = (await this.connection.tooling.query(`SELECT Branch, MajorVersion, MinorVersion, PatchVersion, BuildNumber FROM Package2Version WHERE SubscriberPackageVersionId='${results.SubscriberPackageVersionId}'`)).records[0];
-            const version = `${this.project.getAliasesFromPackageId(results.Package2Id).join()}@${versionResult.MajorVersion ?? 0}.${versionResult.MinorVersion ?? 0}.${versionResult.PatchVersion ?? 0}`;
+            const aliases = this.project.getAliasesFromPackageId(results.Package2Id);
+            if (aliases.length === 0) {
+                throw messages.createError('packageAliasNotFound', [results.Package2Id]);
+            }
+            const version = `${aliases[0]}@${versionResult.MajorVersion ?? 0}.${versionResult.MinorVersion ?? 0}.${versionResult.PatchVersion ?? 0}`;
             const build = versionResult.BuildNumber ? `-${versionResult.BuildNumber}` : '';
             const branch = versionResult.Branch ? `-${versionResult.Branch}` : '';
             // set packageAliases entry '<package>@<major>.<minor>.<patch>-<build>-<branch>: <result.subscriberPackageVersionId>'

package/lib/package/subscriberPackageVersion.d.ts

@@ -5,7 +5,18 @@ import { InstalledPackages, PackageInstallCreateRequest, PackageInstallOptions,
 import { VersionNumber } from './versionNumber';
 export declare const SubscriberPackageVersionFields: string[];
 /**
- * A class that represents a SubscriberPackageVersion
+ * Provides the ability to get, list, install, and uninstall 2nd
+ * generation subscriber package versions.
+ *
+ * **Examples**
+ *
+ * List all 2GP installed packages in the org:
+ *
+ * `const installedPkgs = await SubscriberPackageVersion.installedList(connection);`
+ *
+ * Install a 2GP subscriber package version:
+ *
+ * `const installStatus = await new SubscriberPackageVersion(options).install(request, options);`
  */
 export declare class SubscriberPackageVersion {
     private options;

package/lib/package/subscriberPackageVersion.js

@@ -75,7 +75,18 @@ const allZeroesInstallOptions = {
     publishTimeout: kit_1.Duration.minutes(0),
 };
 /**
- * A class that represents a SubscriberPackageVersion
+ * Provides the ability to get, list, install, and uninstall 2nd
+ * generation subscriber package versions.
+ *
+ * **Examples**
+ *
+ * List all 2GP installed packages in the org:
+ *
+ * `const installedPkgs = await SubscriberPackageVersion.installedList(connection);`
+ *
+ * Install a 2GP subscriber package version:
+ *
+ * `const installStatus = await new SubscriberPackageVersion(options).install(request, options);`
  */
 class SubscriberPackageVersion {
     constructor(options) {

package/lib/package1/package1Version.d.ts

@@ -3,9 +3,19 @@ import { Duration } from '@salesforce/kit';
 import { IPackageVersion1GP, Package1VersionCreateRequest, PackagingSObjects } from '../interfaces';
 import MetadataPackageVersion = PackagingSObjects.MetadataPackageVersion;
 /**
- * Package1Version class - Class to be used with 1st generation package versions
+ * Provides the ability to get, list, and create 1st generation package versions.
  *
- * implementation examples can be seen here: https://github.com/salesforcecli/plugin-packaging/tree/main/src/commands/force/package1/
+ * **Examples**
+ *
+ * List all 1GP package versions in the org:
+ *
+ * `const pkgList = await Package1Version.list(connection);`
+ *
+ * Create a new 1GP package vesion in the org:
+ *
+ * `const myPkg = await Package1Version.create(connection, options, pollingOptions);`
+ *
+ * More implementation examples are in the plugin here: https://github.com/salesforcecli/plugin-packaging/tree/main/src/commands/force/package1/
  */
 export declare class Package1Version implements IPackageVersion1GP {
     private connection;

package/lib/package1/package1Version.js

@@ -14,9 +14,19 @@ const interfaces_1 = require("../interfaces");
 core_1.Messages.importMessagesDirectory(__dirname);
 const messages = core_1.Messages.loadMessages('@salesforce/packaging', 'package1Version');
 /**
- * Package1Version class - Class to be used with 1st generation package versions
+ * Provides the ability to get, list, and create 1st generation package versions.
  *
- * implementation examples can be seen here: https://github.com/salesforcecli/plugin-packaging/tree/main/src/commands/force/package1/
+ * **Examples**
+ *
+ * List all 1GP package versions in the org:
+ *
+ * `const pkgList = await Package1Version.list(connection);`
+ *
+ * Create a new 1GP package vesion in the org:
+ *
+ * `const myPkg = await Package1Version.create(connection, options, pollingOptions);`
+ *
+ * More implementation examples are in the plugin here: https://github.com/salesforcecli/plugin-packaging/tree/main/src/commands/force/package1/
  */
 class Package1Version {
     /**

package/messages/package_version.md

@@ -17,3 +17,7 @@ The provided package uninstall request ID: [%s] is invalid. It must be a 15 or 1
 # packageVersionInstallRequestNotFound
 
 The provided package install request ID: [%s] could not be found.
+
+# packageAliasNotFound
+
+The provided package id: [%s] could not be resolved to an alias.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/packaging",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Packaging library for the Salesforce packaging platform",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",