@salesforce/core 3.16.2 → 3.17.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.
 
+## [3.17.0](https://github.com/forcedotcom/sfdx-core/compare/v3.16.2...v3.17.0) (2022-05-12)
+
+### Features
+
+- sandboxStatus for v3 ([#571](https://github.com/forcedotcom/sfdx-core/issues/571)) ([60a004b](https://github.com/forcedotcom/sfdx-core/commit/60a004b663d918ec8b37d6ded7ddf12ce112b7f8))
+
 ### [3.16.2](https://github.com/forcedotcom/sfdx-core/compare/v3.16.1...v3.16.2) (2022-05-11)
 
 ### [3.16.1](https://github.com/forcedotcom/sfdx-core/compare/v3.16.0...v3.16.1) (2022-05-11)

package/lib/org/org.d.ts

@@ -140,6 +140,17 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
      * @returns {ScratchOrgCreateResult}
      */
     scratchOrgCreate(options: ScratchOrgRequest): Promise<ScratchOrgCreateResult>;
+    /**
+     * Reports sandbox org creation status. If the org is ready, authenticates to the org.
+     *
+     * @param {sandboxname} string the sandbox name
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     * @returns {SandboxProcessObject} the sandbox process object
+     */
+    sandboxStatus(sandboxname: string, options: {
+        wait?: Duration;
+        interval?: Duration;
+    }): Promise<SandboxProcessObject>;
     /**
      * Clean all data files in the org's data path. Usually <workspace>/.sfdx/orgs/<username>.
      *
@@ -348,6 +359,29 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
      * **Throws** *{@link SfError}{ name: 'NotSupportedError' }* Throws an unsupported error.
      */
     protected getDefaultOptions(): Org.Options;
+    /**
+     * Gets the sandboxProcessObject and then polls for it to complete.
+     *
+     * @param sandboxProcessName sanbox process name
+     * @param options { wait?: Duration; interval?: Duration }
+     * @returns {SandboxProcessObject} The SandboxProcessObject for the sandbox
+     */
+    private authWithRetriesByName;
+    /**
+     * Polls the sandbox org for the sandboxProcessObject.
+     *
+     * @param sandboxProcessObj: The in-progress sandbox signup request
+     * @param options { wait?: Duration; interval?: Duration }
+     * @returns {SandboxProcessObject}
+     */
+    private authWithRetries;
+    /**
+     * Query the sandbox for the SandboxProcessObject by sandbox name
+     *
+     * @param sandboxName The name of the sandbox to query
+     * @returns {SandboxProcessObject} The SandboxProcessObject for the sandbox
+     */
+    private queryLatestSandboxProcessBySandboxName;
     private queryProduction;
     private destroySandbox;
     private destroyScratchOrg;

package/lib/org/org.js

@@ -41,6 +41,8 @@ const messages = messages_1.Messages.load('@salesforce/core', 'org', [
     'scratchOrgNotFound',
     'AuthInfoOrgIdUndefined',
     'sandboxCreateNotComplete',
+    'SandboxProcessNotFoundBySandboxName',
+    'MultiSandboxProcessNotFoundBySandboxName',
 ]);
 var OrgTypes;
 (function (OrgTypes) {
@@ -192,6 +194,16 @@ class Org extends kit_1.AsyncOptionalCreatable {
     async scratchOrgCreate(options) {
         return (0, scratchOrgCreate_1.scratchOrgCreate)({ ...options, hubOrg: this });
     }
+    /**
+     * Reports sandbox org creation status. If the org is ready, authenticates to the org.
+     *
+     * @param {sandboxname} string the sandbox name
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     * @returns {SandboxProcessObject} the sandbox process object
+     */
+    async sandboxStatus(sandboxname, options) {
+        return this.authWithRetriesByName(sandboxname, options);
+    }
     /**
      * Clean all data files in the org's data path. Usually <workspace>/.sfdx/orgs/<username>.
      *
@@ -710,6 +722,58 @@ class Org extends kit_1.AsyncOptionalCreatable {
     getDefaultOptions() {
         throw new sfError_1.SfError('Not Supported', 'NotSupportedError');
     }
+    /**
+     * Gets the sandboxProcessObject and then polls for it to complete.
+     *
+     * @param sandboxProcessName sanbox process name
+     * @param options { wait?: Duration; interval?: Duration }
+     * @returns {SandboxProcessObject} The SandboxProcessObject for the sandbox
+     */
+    async authWithRetriesByName(sandboxProcessName, options) {
+        return this.authWithRetries(await this.queryLatestSandboxProcessBySandboxName(sandboxProcessName), options);
+    }
+    /**
+     * Polls the sandbox org for the sandboxProcessObject.
+     *
+     * @param sandboxProcessObj: The in-progress sandbox signup request
+     * @param options { wait?: Duration; interval?: Duration }
+     * @returns {SandboxProcessObject}
+     */
+    async authWithRetries(sandboxProcessObj, options = {
+        wait: kit_1.Duration.minutes(0),
+        interval: kit_1.Duration.seconds(30),
+    }) {
+        const [wait, pollInterval] = this.validateWaitOptions(options);
+        this.logger.debug(`AuthWithRetries sandboxProcessObj ${sandboxProcessObj}, max wait time of ${wait.minutes} minutes`);
+        return this.pollStatusAndAuth({
+            sandboxProcessObj,
+            wait,
+            pollInterval,
+        });
+    }
+    /**
+     * Query the sandbox for the SandboxProcessObject by sandbox name
+     *
+     * @param sandboxName The name of the sandbox to query
+     * @returns {SandboxProcessObject} The SandboxProcessObject for the sandbox
+     */
+    async queryLatestSandboxProcessBySandboxName(sandboxNameIn) {
+        var _a;
+        const { tooling } = this.getConnection();
+        this.logger.debug('QueryLatestSandboxProcessBySandboxName called with SandboxName: %s ', sandboxNameIn);
+        const queryStr = `SELECT Id, Status, SandboxName, SandboxInfoId, LicenseType, CreatedDate, CopyProgress, SandboxOrganization, SourceId, Description, EndDate FROM SandboxProcess WHERE SandboxName='${sandboxNameIn}' AND Status != 'D' ORDER BY CreatedDate DESC LIMIT 1`;
+        const queryResult = await tooling.query(queryStr);
+        this.logger.debug('Return from calling queryToolingApi: %s ', queryResult);
+        if (((_a = queryResult === null || queryResult === void 0 ? void 0 : queryResult.records) === null || _a === void 0 ? void 0 : _a.length) === 1) {
+            return queryResult.records[0];
+        }
+        else if (queryResult.records && queryResult.records.length > 1) {
+            throw messages.createError('MultiSandboxProcessNotFoundBySandboxName', [sandboxNameIn]);
+        }
+        else {
+            throw messages.createError('SandboxProcessNotFoundBySandboxName', [sandboxNameIn]);
+        }
+    }
     async queryProduction(org, field, value) {
         return org.connection.singleRecordQuery(`SELECT SandboxInfoId FROM SandboxProcess WHERE ${field} ='${value}' AND Status NOT IN ('D', 'E')`, { tooling: true });
     }

package/messages/org.md

@@ -53,3 +53,11 @@ AuthInfo orgId is undefined.
 # sandboxCreateNotComplete
 
 The sandbox creation has not completed.
+
+# SandboxProcessNotFoundBySandboxName
+
+We can't find a SandboxProcess with the SandboxName %s.
+
+# MultiSandboxProcessNotFoundBySandboxName
+
+We found more than one SandboxProcess with the SandboxName %s.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/core",
-  "version": "3.16.2",
+  "version": "3.17.0",
   "description": "Core libraries to interact with SFDX projects, orgs, and APIs.",
   "main": "lib/exported",
   "types": "lib/exported.d.ts",