@salesforce/core 2.32.0 → 2.33.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.
 
+## [2.33.0](https://github.com/forcedotcom/sfdx-core/compare/v2.32.0...v2.33.0) (2021-12-14)
+
+### Features
+
+- sandbox creation ([314dcf1](https://github.com/forcedotcom/sfdx-core/commit/314dcf164d93bd0e3a5f4763a4dfcdde7d0cb14a))
+
 ## [2.32.0](https://github.com/forcedotcom/sfdx-core/compare/v2.31.1...v2.32.0) (2021-12-14)
 
 ### Features

package/lib/exported.d.ts

@@ -18,7 +18,7 @@ export { SfdcUrl } from './util/sfdcUrl';
 export { getJwtAudienceUrl } from './util/getJwtAudienceUrl';
 export { Fields, FieldValue, LoggerLevel, LoggerLevelValue, LogLine, LoggerOptions, LoggerStream, Logger, } from './logger';
 export { Messages } from './messages';
-export { Org } from './org';
+export { Org, SandboxProcessObject, StatusEvent, SandboxEvents, SandboxUserAuthResponse, SandboxUserAuthRequest, SandboxRequest, OrgTypes, ResultEvent, } from './org';
 export { PackageDir, NamedPackageDir, PackageDirDependency, SfdxProject, SfdxProjectJson } from './sfdxProject';
 export { SchemaPrinter } from './schema/printer';
 export { SchemaValidator } from './schema/validator';

package/lib/exported.js

@@ -16,7 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PermissionSetAssignment = exports.User = exports.REQUIRED_FIELDS = exports.DefaultUserFields = exports.MyDomainResolver = exports.StreamingClient = exports.CometClient = exports.PollingClient = exports.SfdxErrorConfig = exports.SfdxError = exports.SchemaValidator = exports.SchemaPrinter = exports.SfdxProjectJson = exports.SfdxProject = exports.Org = exports.Messages = exports.Logger = exports.LoggerLevel = exports.getJwtAudienceUrl = exports.SfdcUrl = exports.WebOAuthServer = exports.Lifecycle = exports.Global = exports.Mode = exports.SFDX_HTTP_HEADERS = exports.Connection = exports.AuthRemover = exports.OAuth2WithVerifier = exports.AuthInfo = exports.ConfigAggregator = exports.Config = exports.OrgUsersConfig = exports.DeviceOauthService = exports.BaseConfigStore = exports.ConfigGroup = exports.ConfigFile = exports.AuthInfoConfig = exports.AliasGroup = exports.Aliases = void 0;
+exports.PermissionSetAssignment = exports.User = exports.REQUIRED_FIELDS = exports.DefaultUserFields = exports.MyDomainResolver = exports.StreamingClient = exports.CometClient = exports.PollingClient = exports.SfdxErrorConfig = exports.SfdxError = exports.SchemaValidator = exports.SchemaPrinter = exports.SfdxProjectJson = exports.SfdxProject = exports.OrgTypes = exports.SandboxEvents = exports.Org = exports.Messages = exports.Logger = exports.LoggerLevel = exports.getJwtAudienceUrl = exports.SfdcUrl = exports.WebOAuthServer = exports.Lifecycle = exports.Global = exports.Mode = exports.SFDX_HTTP_HEADERS = exports.Connection = exports.AuthRemover = exports.OAuth2WithVerifier = exports.AuthInfo = exports.ConfigAggregator = exports.Config = exports.OrgUsersConfig = exports.DeviceOauthService = exports.BaseConfigStore = exports.ConfigGroup = exports.ConfigFile = exports.AuthInfoConfig = exports.AliasGroup = exports.Aliases = void 0;
 const messages_1 = require("./messages");
 messages_1.Messages.importMessagesDirectory(__dirname);
 var aliases_1 = require("./config/aliases");
@@ -64,6 +64,8 @@ var messages_2 = require("./messages");
 Object.defineProperty(exports, "Messages", { enumerable: true, get: function () { return messages_2.Messages; } });
 var org_1 = require("./org");
 Object.defineProperty(exports, "Org", { enumerable: true, get: function () { return org_1.Org; } });
+Object.defineProperty(exports, "SandboxEvents", { enumerable: true, get: function () { return org_1.SandboxEvents; } });
+Object.defineProperty(exports, "OrgTypes", { enumerable: true, get: function () { return org_1.OrgTypes; } });
 var sfdxProject_1 = require("./sfdxProject");
 Object.defineProperty(exports, "SfdxProject", { enumerable: true, get: function () { return sfdxProject_1.SfdxProject; } });
 Object.defineProperty(exports, "SfdxProjectJson", { enumerable: true, get: function () { return sfdxProject_1.SfdxProjectJson; } });

package/lib/org.d.ts

@@ -1,10 +1,61 @@
-import { AsyncCreatable } from '@salesforce/kit';
+import { AsyncCreatable, Duration } from '@salesforce/kit';
 import { AnyJson, JsonMap, Optional } from '@salesforce/ts-types';
 import { AuthFields, AuthInfo } from './authInfo';
 import { ConfigAggregator } from './config/configAggregator';
 import { OrgUsersConfig } from './config/orgUsersConfig';
 import { SandboxOrgConfig } from './config/sandboxOrgConfig';
 import { Connection } from './connection';
+export declare enum OrgTypes {
+    Scratch = "scratch",
+    Sandbox = "sandbox"
+}
+export interface StatusEvent {
+    sandboxProcessObj: SandboxProcessObject;
+    interval: number;
+    retries: number;
+    waitingOnAuth: boolean;
+}
+export interface ResultEvent {
+    sandboxProcessObj: SandboxProcessObject;
+    sandboxRes: SandboxUserAuthResponse;
+}
+export interface SandboxUserAuthRequest {
+    sandboxName: string;
+    clientId: string;
+    callbackUrl: string;
+}
+export declare enum SandboxEvents {
+    EVENT_STATUS = "status",
+    EVENT_ASYNC_RESULT = "asyncResult",
+    EVENT_RESULT = "result",
+    EVENT_AUTH = "auth"
+}
+export interface SandboxUserAuthResponse {
+    authUserName: string;
+    authCode: string;
+    instanceUrl: string;
+    loginUrl: string;
+}
+export interface SandboxProcessObject {
+    Id: string;
+    Status: string;
+    SandboxName: string;
+    SandboxInfoId: string;
+    LicenseType: string;
+    CreatedDate: string;
+    SandboxOrganization?: string;
+    CopyProgress?: number;
+    SourceId?: string;
+    Description?: string;
+    ApexClassId?: string;
+    EndDate?: string;
+}
+export declare type SandboxRequest = {
+    SandboxName: string;
+    LicenseType?: string;
+    SourceId?: string;
+    Description?: string;
+};
 /**
  * Provides a way to manage a locally authenticated Org.
  *
@@ -41,6 +92,17 @@ export declare class Org extends AsyncCreatable<Org.Options> {
      * @ignore
      */
     constructor(options: Org.Options);
+    /**
+     * create a sandbox from a production org
+     * 'this' needs to be a production org with sandbox licenses available
+     *
+     * @param sandboxReq SandboxRequest options to create the sandbox with
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     */
+    createSandbox(sandboxReq: SandboxRequest, options: {
+        wait?: Duration;
+        interval?: Duration;
+    }): Promise<SandboxProcessObject>;
     /**
      * Clean all data files in the org's data path. Usually <workspace>/.sfdx/orgs/<username>.
      *
@@ -233,6 +295,32 @@ export declare class Org extends AsyncCreatable<Org.Options> {
      * @param throwWhenRemoveFails true if manageDelete should throw or not if the deleted fails.
      */
     private removeSandboxConfig;
+    private writeSandboxAuthFile;
+    /**
+     * Polls for the new sandbox to be created - and will write the associated auth files
+     *
+     * @private
+     * @param options
+     *  sandboxProcessObj: The in-progress sandbox signup request
+     *  retries: the number of retries to poll for every 30s
+     *  shouldPoll: wait for polling, or just return
+     *  pollInterval: Duration to sleep between poll events, default 30 seconds
+     */
+    private pollStatusAndAuth;
+    /**
+     * query SandboxProcess via SandboxInfoId
+     *
+     * @param id SandboxInfoId to query for
+     * @private
+     */
+    private querySandboxProcess;
+    /**
+     * determines if the sandbox has successfully been created
+     *
+     * @param sandboxProcessObj sandbox signup progeress
+     * @private
+     */
+    private sandboxSignupComplete;
 }
 export declare namespace Org {
     /**

package/lib/org.js

@@ -6,7 +6,7 @@
  * 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.Org = void 0;
+exports.Org = exports.SandboxEvents = exports.OrgTypes = void 0;
 const path_1 = require("path");
 const kit_1 = require("@salesforce/kit");
 const ts_types_1 = require("@salesforce/ts-types");
@@ -19,10 +19,24 @@ const orgUsersConfig_1 = require("./config/orgUsersConfig");
 const sandboxOrgConfig_1 = require("./config/sandboxOrgConfig");
 const connection_1 = require("./connection");
 const global_1 = require("./global");
+const lifecycleEvents_1 = require("./lifecycleEvents");
 const logger_1 = require("./logger");
 const sfdxError_1 = require("./sfdxError");
 const fs_1 = require("./util/fs");
 const sfdc_1 = require("./util/sfdc");
+const webOAuthServer_1 = require("./webOAuthServer");
+var OrgTypes;
+(function (OrgTypes) {
+    OrgTypes["Scratch"] = "scratch";
+    OrgTypes["Sandbox"] = "sandbox";
+})(OrgTypes = exports.OrgTypes || (exports.OrgTypes = {}));
+var SandboxEvents;
+(function (SandboxEvents) {
+    SandboxEvents["EVENT_STATUS"] = "status";
+    SandboxEvents["EVENT_ASYNC_RESULT"] = "asyncResult";
+    SandboxEvents["EVENT_RESULT"] = "result";
+    SandboxEvents["EVENT_AUTH"] = "auth";
+})(SandboxEvents = exports.SandboxEvents || (exports.SandboxEvents = {}));
 /**
  * Provides a way to manage a locally authenticated Org.
  *
@@ -58,6 +72,33 @@ class Org extends kit_1.AsyncCreatable {
         this.status = Org.Status.UNKNOWN;
         this.options = options;
     }
+    /**
+     * create a sandbox from a production org
+     * 'this' needs to be a production org with sandbox licenses available
+     *
+     * @param sandboxReq SandboxRequest options to create the sandbox with
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     */
+    async createSandbox(sandboxReq, options) {
+        var _a;
+        this.logger.debug('CreateSandbox called with SandboxRequest: %s ', sandboxReq);
+        const createResult = await this.connection.tooling.create('SandboxInfo', sandboxReq);
+        this.logger.debug('Return from calling tooling.create: %s ', createResult);
+        if (Array.isArray(createResult) || !createResult.success) {
+            throw sfdxError_1.SfdxError.create('@salesforce/core', 'org', 'SandboxInfoCreateFailed', [JSON.stringify(createResult)]);
+        }
+        const sandboxCreationProgress = await this.querySandboxProcess(createResult.id);
+        this.logger.debug('Return from calling singleRecordQuery with tooling: %s', sandboxCreationProgress);
+        const retries = options.wait ? options.wait.seconds / kit_1.Duration.seconds(30).seconds : 0;
+        this.logger.debug('pollStatusAndAuth sandboxProcessObj %s, maxPollingRetries %i', sandboxCreationProgress, retries);
+        const pollInterval = (_a = options.interval) !== null && _a !== void 0 ? _a : kit_1.Duration.seconds(30);
+        return this.pollStatusAndAuth({
+            sandboxProcessObj: sandboxCreationProgress,
+            retries,
+            shouldPoll: retries > 0,
+            pollInterval,
+        });
+    }
     /**
      * Clean all data files in the org's data path. Usually <workspace>/.sfdx/orgs/<username>.
      *
@@ -594,6 +635,7 @@ class Org extends kit_1.AsyncCreatable {
      *
      * @param throwWhenRemoveFails true if manageDelete should throw or not if the deleted fails.
      */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     async removeUsers(throwWhenRemoveFails) {
         this.logger.debug(`Removing users associate with org: ${this.getOrgId()}`);
         const config = await this.retrieveOrgUsersConfig();
@@ -637,6 +679,167 @@ class Org extends kit_1.AsyncCreatable {
             await this.manageDelete(async () => await sandboxOrgConfig.unlink(), sandboxOrgConfig.getPath(), throwWhenRemoveFails);
         }
     }
+    async writeSandboxAuthFile(sandboxProcessObj, sandboxRes) {
+        this.logger.debug('writeSandboxAuthFile sandboxProcessObj: %s, sandboxRes: %s', sandboxProcessObj, sandboxRes);
+        if (sandboxRes.authUserName) {
+            const productionAuthFields = this.connection.getAuthInfoFields();
+            this.logger.debug('Result from getAuthInfoFields: AuthFields %s', productionAuthFields);
+            // let's do headless auth via jwt (if we have privateKey) or web auth
+            const oauth2Options = {
+                loginUrl: sandboxRes.loginUrl,
+                instanceUrl: sandboxRes.instanceUrl,
+                username: sandboxRes.authUserName,
+            };
+            // If we don't have a privateKey then we assume it's web auth.
+            if (!productionAuthFields.privateKey) {
+                oauth2Options.redirectUri = `http://localhost:${await webOAuthServer_1.WebOAuthServer.determineOauthPort()}/OauthRedirect`;
+                oauth2Options.authCode = sandboxRes.authCode;
+            }
+            const authInfo = await authInfo_1.AuthInfo.create({
+                username: sandboxRes.authUserName,
+                oauth2Options,
+                parentUsername: productionAuthFields.username,
+            });
+            await authInfo.save();
+            const sandboxOrg = await Org.create({ aliasOrUsername: authInfo.getUsername() });
+            await sandboxOrg.setSandboxOrgConfigField(sandboxOrgConfig_1.SandboxOrgConfig.Fields.PROD_ORG_USERNAME, 
+            // we couldn't get this far into the process without a production org so username will be there
+            productionAuthFields.username);
+            await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_RESULT, {
+                sandboxProcessObj,
+                sandboxRes,
+            });
+        }
+        else {
+            // no authed sandbox user, error
+            throw sfdxError_1.SfdxError.create('@salesforce/core', 'org', 'MissingAuthUsername', [sandboxProcessObj.SandboxName]);
+        }
+    }
+    /**
+     * Polls for the new sandbox to be created - and will write the associated auth files
+     *
+     * @private
+     * @param options
+     *  sandboxProcessObj: The in-progress sandbox signup request
+     *  retries: the number of retries to poll for every 30s
+     *  shouldPoll: wait for polling, or just return
+     *  pollInterval: Duration to sleep between poll events, default 30 seconds
+     */
+    async pollStatusAndAuth(options) {
+        const { sandboxProcessObj, retries, shouldPoll, pollInterval } = options;
+        this.logger.debug('PollStatusAndAuth called with SandboxProcessObject%s, retries %s', sandboxProcessObj, retries);
+        const lifecycle = lifecycleEvents_1.Lifecycle.getInstance();
+        let pollFinished = false;
+        let waitingOnAuth = false;
+        const sandboxInfo = await this.sandboxSignupComplete(sandboxProcessObj);
+        if (sandboxInfo) {
+            await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_AUTH, sandboxInfo);
+            try {
+                this.logger.debug('sandbox signup complete with %s', sandboxInfo);
+                await this.writeSandboxAuthFile(sandboxProcessObj, sandboxInfo);
+                pollFinished = true;
+            }
+            catch (err) {
+                this.logger.debug('Exception while calling writeSandboxAuthFile %s', err);
+                if ((err === null || err === void 0 ? void 0 : err.name) === 'JWTAuthError' && (err === null || err === void 0 ? void 0 : err.stack.includes("user hasn't approved"))) {
+                    waitingOnAuth = true;
+                }
+                else {
+                    throw sfdxError_1.SfdxError.wrap(err);
+                }
+            }
+        }
+        if (!pollFinished) {
+            if (retries > 0) {
+                // emit the signup progress of the sandbox and query the production org again after waiting the interval
+                await Promise.all([
+                    await lifecycle.emit(SandboxEvents.EVENT_STATUS, {
+                        sandboxProcessObj,
+                        interval: pollInterval.seconds,
+                        retries,
+                        waitingOnAuth,
+                    }),
+                    await kit_1.sleep(pollInterval),
+                ]);
+                const polledSandboxProcessObj = await this.querySandboxProcess(sandboxProcessObj.SandboxInfoId);
+                return this.pollStatusAndAuth({
+                    sandboxProcessObj: polledSandboxProcessObj,
+                    retries: retries - 1,
+                    shouldPoll,
+                    pollInterval,
+                });
+            }
+            else {
+                if (shouldPoll) {
+                    // timed out on retries
+                    throw sfdxError_1.SfdxError.create('@salesforce/core', 'org', 'OrgPollingTimeout', [sandboxProcessObj.Status]);
+                }
+                else {
+                    // The user didn't want us to poll, so simply return the status
+                    // simply report status and exit
+                    await lifecycle.emit(SandboxEvents.EVENT_ASYNC_RESULT, sandboxProcessObj);
+                }
+            }
+        }
+        return sandboxProcessObj;
+    }
+    /**
+     * query SandboxProcess via SandboxInfoId
+     *
+     * @param id SandboxInfoId to query for
+     * @private
+     */
+    async querySandboxProcess(id) {
+        const queryStr = `SELECT Id, Status, SandboxName, SandboxInfoId, LicenseType, CreatedDate, CopyProgress, SandboxOrganization, SourceId, Description, EndDate FROM SandboxProcess WHERE SandboxInfoId='${id}' AND Status != 'D'`;
+        return await this.connection.singleRecordQuery(queryStr, {
+            tooling: true,
+        });
+    }
+    /**
+     * determines if the sandbox has successfully been created
+     *
+     * @param sandboxProcessObj sandbox signup progeress
+     * @private
+     */
+    async sandboxSignupComplete(sandboxProcessObj) {
+        this.logger.debug('sandboxSignupComplete called with SandboxProcessObject %s', sandboxProcessObj);
+        if (!sandboxProcessObj.EndDate) {
+            return;
+        }
+        try {
+            // call server side /sandboxAuth API to auth the sandbox org user with the connected app
+            const authFields = this.connection.getAuthInfoFields();
+            const callbackUrl = `http://localhost:${await webOAuthServer_1.WebOAuthServer.determineOauthPort()}/OauthRedirect`;
+            const sandboxReq = {
+                // the sandbox signup has been completed on production, we have production clientId by this point
+                clientId: authFields.clientId,
+                sandboxName: sandboxProcessObj.SandboxName,
+                callbackUrl,
+            };
+            this.logger.debug('Calling sandboxAuth with SandboxUserAuthRequest %s', sandboxReq);
+            const url = `${this.connection.tooling._baseUrl()}/sandboxAuth`;
+            const params = {
+                method: 'POST',
+                url,
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(sandboxReq),
+            };
+            const result = await this.connection.tooling.request(params);
+            this.logger.debug('Result of calling sandboxAuth %s', result);
+            return result;
+        }
+        catch (err) {
+            // There are cases where the endDate is set before the sandbox has actually completed.
+            // In that case, the sandboxAuth call will throw a specific exception.
+            if ((err === null || err === void 0 ? void 0 : err.name) === 'INVALID_STATUS') {
+                this.logger.debug('Error while authenticating the user %s', err === null || err === void 0 ? void 0 : err.toString());
+            }
+            else {
+                // If it fails for any unexpected reason, just pass that through
+                throw sfdxError_1.SfdxError.wrap(err);
+            }
+        }
+    }
 }
 exports.Org = Org;
 (function (Org) {

package/messages/org.json

@@ -6,5 +6,8 @@
   "InsufficientAccessToDelete": "You do not have the appropriate permissions to delete a scratch org. Please contact your Salesforce admin.",
   "ScratchOrgNotFound": "Attempting to delete an expired or deleted org",
   "SandboxDeleteFailed": "The sandbox org deletion failed with a result of %s.",
-  "SandboxNotFound": "We can't find a SandboxProcess for the sandbox org %s."
+  "SandboxNotFound": "We can't find a SandboxProcess for the sandbox org %s.",
+  "SandboxInfoCreateFailed": "The sandbox org creation failed with a result of %s.",
+  "MissingAuthUsername": "The sandbox %s does not have an authorized username.",
+  "OrgPollingTimeout": "Sandbox status is %s; timed out waiting for completion."
 }

package/package.json

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