@salesforce/core 6.5.6 → 6.6.0

package/lib/config/sandboxProcessCache.d.ts

@@ -2,8 +2,9 @@ import { SandboxProcessObject, SandboxRequest } from '../org/org';
 import { TTLConfig } from './ttlConfig';
 export type SandboxRequestCacheEntry = {
     alias?: string;
-    setDefault: boolean;
+    setDefault?: boolean;
     prodOrgUsername: string;
+    action: 'Create' | 'Refresh';
     sandboxProcessObject: Partial<SandboxProcessObject>;
     sandboxRequest: Partial<SandboxRequest>;
     tracksSource?: boolean;

package/lib/exported.d.ts

@@ -20,7 +20,7 @@ export { SfdcUrl } from './util/sfdcUrl';
 export { getJwtAudienceUrl } from './util/getJwtAudienceUrl';
 export { Fields, FieldValue, LoggerLevel, LoggerLevelValue, LogLine, LoggerOptions, Logger } from './logger/logger';
 export { Messages, StructuredMessage } from './messages';
-export { Org, SandboxProcessObject, StatusEvent, SandboxEvents, SandboxUserAuthResponse, SandboxUserAuthRequest, SandboxRequest, ResumeSandboxRequest, OrgTypes, ResultEvent, ScratchOrgRequest, } from './org/org';
+export { Org, SandboxProcessObject, StatusEvent, SandboxInfo, SandboxEvents, SandboxUserAuthResponse, SandboxUserAuthRequest, SandboxRequest, ResumeSandboxRequest, OrgTypes, ResultEvent, ScratchOrgRequest, } from './org/org';
 export { OrgConfigProperties, ORG_CONFIG_ALLOWED_PROPERTIES } from './org/orgConfigProperties';
 export { PackageDir, NamedPackageDir, PackageDirDependency, SfProject, SfProjectJson } from './sfProject';
 export { SchemaValidator } from './schema/validator';

package/lib/org/org.d.ts

@@ -71,6 +71,24 @@ export type ResumeSandboxRequest = {
     SandboxName?: string;
     SandboxProcessObjId?: string;
 };
+export type SandboxInfo = {
+    Id: string;
+    IsDeleted: boolean;
+    CreatedDate: string;
+    CreatedById: string;
+    LastModifiedDate: string;
+    LastModifiedById: string;
+    SandboxName: string;
+    LicenseType: 'DEVELOPER' | 'DEVELOPER PRO' | 'PARTIAL' | 'FULL';
+    TemplateId?: string;
+    HistoryDays: -1 | 0 | 10 | 20 | 30 | 60 | 90 | 120 | 150 | 180;
+    CopyChatter: boolean;
+    AutoActivate: boolean;
+    ApexClassId?: string;
+    Description?: string;
+    SourceId?: string;
+    CopyArchivedActivities?: boolean;
+};
 export type ScratchOrgRequest = Omit<ScratchOrgCreateOptions, 'hubOrg'>;
 export type SandboxFields = {
     sandboxOrgId: string;
@@ -130,6 +148,18 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
         interval?: Duration;
         async?: boolean;
     }): Promise<SandboxProcessObject>;
+    /**
+     * Refresh (update) a sandbox from a production org.
+     * 'this' needs to be a production org with sandbox licenses available
+     *
+     * @param sandboxInfo SandboxInfo to update the sandbox with
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     */
+    refreshSandbox(sandboxInfo: SandboxInfo, options?: {
+        wait?: Duration;
+        interval?: Duration;
+        async?: boolean;
+    }): Promise<SandboxProcessObject>;
     /**
      *
      * @param sandboxReq SandboxRequest options to create the sandbox with
@@ -142,10 +172,10 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
         interval?: Duration;
     }): Promise<SandboxProcessObject>;
     /**
-     * Resume a sandbox creation from a production org.
+     * Resume a sandbox create or refresh from a production org.
      * `this` needs to be a production org with sandbox licenses available.
      *
-     * @param resumeSandboxRequest SandboxRequest options to create the sandbox with
+     * @param resumeSandboxRequest SandboxRequest options to create/refresh the sandbox with
      * @param options Wait: The amount of time to wait (default: 0 minutes) before timing out,
      * Interval: The time interval (default: 30 seconds) between polling
      */

package/lib/org/org.js

@@ -52,7 +52,7 @@ const authInfo_1 = require("./authInfo");
 const scratchOrgCreate_1 = require("./scratchOrgCreate");
 const orgConfigProperties_1 = require("./orgConfigProperties");
 ;
-const messages = new messages_1.Messages('@salesforce/core', 'org', new Map([["notADevHub", "The provided dev hub username %s is not a valid dev hub."], ["noUsernameFound", "No username found."], ["noDevHubFound", "Unable to associate this scratch org with a DevHub."], ["deleteOrgHubError", "The Dev Hub org cannot be deleted."], ["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 %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."], ["NotFoundOnDevHub", "The scratch org does not belong to the dev hub username %s."], ["AuthInfoOrgIdUndefined", "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."], ["sandboxNotResumable", "The sandbox %s cannot resume with status of %s."]]));
+const messages = new messages_1.Messages('@salesforce/core', 'org', new Map([["notADevHub", "The provided dev hub username %s is not a valid dev hub."], ["noUsernameFound", "No username found."], ["noDevHubFound", "Unable to associate this scratch org with a DevHub."], ["deleteOrgHubError", "The Dev Hub org cannot be deleted."], ["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 %s."], ["sandboxInfoCreateFailed", "The sandbox org creation failed with a result of %s."], ["sandboxInfoRefreshFailed", "The sandbox org refresh 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."], ["NotFoundOnDevHub", "The scratch org does not belong to the dev hub username %s."], ["AuthInfoOrgIdUndefined", "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."], ["sandboxNotResumable", "The sandbox %s cannot resume with status of %s."]]));
 var OrgTypes;
 (function (OrgTypes) {
     OrgTypes["Scratch"] = "scratch";
@@ -72,6 +72,19 @@ function sandboxIsResumable(value) {
     return resumableSandboxStatus.includes(value);
 }
 exports.sandboxIsResumable = sandboxIsResumable;
+const sandboxProcessFields = [
+    'Id',
+    'Status',
+    'SandboxName',
+    'SandboxInfoId',
+    'LicenseType',
+    'CreatedDate',
+    'CopyProgress',
+    'SandboxOrganization',
+    'SourceId',
+    'Description',
+    'EndDate',
+];
 /**
  * Provides a way to manage a locally authenticated Org.
  *
@@ -141,6 +154,46 @@ class Org extends kit_1.AsyncOptionalCreatable {
             pollInterval,
         });
     }
+    /**
+     * Refresh (update) a sandbox from a production org.
+     * 'this' needs to be a production org with sandbox licenses available
+     *
+     * @param sandboxInfo SandboxInfo to update the sandbox with
+     * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
+     */
+    async refreshSandbox(sandboxInfo, options = {
+        wait: kit_1.Duration.minutes(6),
+        async: false,
+        interval: kit_1.Duration.seconds(30),
+    }) {
+        this.logger.debug(sandboxInfo, 'RefreshSandbox called with SandboxInfo');
+        const refreshResult = await this.connection.tooling.update('SandboxInfo', sandboxInfo);
+        this.logger.debug(refreshResult, 'Return from calling tooling.update');
+        if (!refreshResult.success) {
+            throw messages.createError('sandboxInfoRefreshFailed', [JSON.stringify(refreshResult)]);
+        }
+        const soql = `SELECT ${sandboxProcessFields.join(',')} FROM SandboxProcess WHERE SandboxName='${sandboxInfo.SandboxName}' ORDER BY CreatedDate DESC`;
+        const sbxProcessObjects = (await this.connection.tooling.query(soql)).records.filter((item) => !item.Status.startsWith('Del'));
+        this.logger.debug(sbxProcessObjects, `SandboxProcesses for ${sandboxInfo.SandboxName}`);
+        // throw if none found
+        if (sbxProcessObjects?.length === 0) {
+            throw new Error(`No SandboxProcesses found for: ${sandboxInfo.SandboxName}`);
+        }
+        const sandboxRefreshProgress = sbxProcessObjects[0];
+        const isAsync = !!options.async;
+        if (isAsync) {
+            // The user didn't want us to poll, so simply return the status
+            await lifecycleEvents_1.Lifecycle.getInstance().emit(SandboxEvents.EVENT_ASYNC_RESULT, sandboxRefreshProgress);
+            return sandboxRefreshProgress;
+        }
+        const [wait, pollInterval] = this.validateWaitOptions(options);
+        this.logger.debug(sandboxRefreshProgress, `refresh - pollStatusAndAuth sandboxProcessObj, max wait time of ${wait.minutes} minutes`);
+        return this.pollStatusAndAuth({
+            sandboxProcessObj: sandboxRefreshProgress,
+            wait,
+            pollInterval,
+        });
+    }
     /**
      *
      * @param sandboxReq SandboxRequest options to create the sandbox with
@@ -154,10 +207,10 @@ class Org extends kit_1.AsyncOptionalCreatable {
         return this.createSandbox(sandboxReq, options);
     }
     /**
-     * Resume a sandbox creation from a production org.
+     * Resume a sandbox create or refresh from a production org.
      * `this` needs to be a production org with sandbox licenses available.
      *
-     * @param resumeSandboxRequest SandboxRequest options to create the sandbox with
+     * @param resumeSandboxRequest SandboxRequest options to create/refresh the sandbox with
      * @param options Wait: The amount of time to wait (default: 0 minutes) before timing out,
      * Interval: The time interval (default: 30 seconds) between polling
      */
@@ -861,7 +914,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
     async queryLatestSandboxProcessBySandboxName(sandboxNameIn) {
         const { tooling } = this.getConnection();
         this.logger.debug(`QueryLatestSandboxProcessBySandboxName called with SandboxName: ${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 queryStr = `SELECT ${sandboxProcessFields.join(',')} FROM SandboxProcess WHERE SandboxName='${sandboxNameIn}' AND Status != 'D' ORDER BY CreatedDate DESC LIMIT 1`;
         const queryResult = await tooling.query(queryStr);
         this.logger.debug(queryResult, 'Return from calling queryToolingApi');
         if (queryResult?.records?.length === 1) {
@@ -1071,6 +1124,17 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 oauth2Options.privateKey = productionAuthFields.privateKey;
                 oauth2Options.clientId = productionAuthFields.clientId;
             }
+            // Before creating the AuthInfo, delete any existing auth files for the sandbox.
+            // This is common when refreshing sandboxes, and will cause AuthInfo to throw
+            // because it doesn't want to overwrite existing auth files.
+            const stateAggregator = await stateAggregator_1.StateAggregator.getInstance();
+            try {
+                await stateAggregator.orgs.read(sandboxRes.authUserName);
+                await stateAggregator.orgs.remove(sandboxRes.authUserName);
+            }
+            catch (e) {
+                // ignore since this is only for deleting existing auth files.
+            }
             const authInfo = await authInfo_1.AuthInfo.create({
                 username: sandboxRes.authUserName,
                 oauth2Options,
@@ -1081,8 +1145,11 @@ class Org extends kit_1.AsyncOptionalCreatable {
                 productionAuthFieldsUsername: productionAuthFields.username,
                 ...oauth2Options,
             }, 'Creating AuthInfo for sandbox');
-            // save auth info for new sandbox
-            await authInfo.save();
+            // save auth info for sandbox
+            await authInfo.save({
+                isScratch: false,
+                isSandbox: true,
+            });
             const sandboxOrgId = authInfo.getFields().orgId;
             if (!sandboxOrgId) {
                 throw messages.createError('AuthInfoOrgIdUndefined');
@@ -1157,7 +1224,7 @@ class Org extends kit_1.AsyncOptionalCreatable {
      * @private
      */
     async querySandboxProcess(where) {
-        const soql = `SELECT Id, Status, SandboxName, SandboxInfoId, LicenseType, CreatedDate, CopyProgress, SandboxOrganization, SourceId, Description, EndDate FROM SandboxProcess WHERE ${where} ORDER BY CreatedDate DESC`;
+        const soql = `SELECT ${sandboxProcessFields.join(',')} FROM SandboxProcess WHERE ${where} ORDER BY CreatedDate DESC`;
         const result = (await this.connection.tooling.query(soql)).records.filter((item) => !item.Status.startsWith('Del'));
         if (result.length === 0) {
             throw new sfError_1.SfError(`No record found for ${soql}`, connection_1.SingleRecordQueryErrors.NoRecords);
@@ -1204,15 +1271,15 @@ class Org extends kit_1.AsyncOptionalCreatable {
             return result;
         }
         catch (err) {
-            const error = err;
+            const error = err instanceof Error ? err : sfError_1.SfError.wrap((0, ts_types_1.isString)(err) ? err : 'unknown');
             // 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 (error?.name === 'INVALID_STATUS') {
-                this.logger.debug('Error while authenticating the user', error?.toString());
+                this.logger.debug('Error while authenticating the user:', error.message);
             }
             else {
-                // If it fails for any unexpected reason, just pass that through
-                throw sfError_1.SfError.wrap(error);
+                // If it fails for any unexpected reason, rethrow
+                throw error;
             }
         }
     }

package/messages/org.md

@@ -34,6 +34,10 @@ We can't find a SandboxProcess for the sandbox %s.
 
 The sandbox org creation failed with a result of %s.
 
+# sandboxInfoRefreshFailed
+
+The sandbox org refresh failed with a result of %s.
+
 # missingAuthUsername
 
 The sandbox %s does not have an authorized username.

package/package.json

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