@salesforce/core 4.0.0 → 4.0.1

package/lib/org/org.d.ts

@@ -1,12 +1,11 @@
 import { AsyncOptionalCreatable, Duration } from '@salesforce/kit';
-import { AnyJson, JsonMap, Optional } from '@salesforce/ts-types';
+import { AnyJson, JsonMap, Nullable, Optional } from '@salesforce/ts-types';
 import { ConfigAggregator } from '../config/configAggregator';
 import { OrgUsersConfig } from '../config/orgUsersConfig';
-import { SandboxOrgConfig } from '../config/sandboxOrgConfig';
 import { Connection } from './connection';
 import { AuthFields, AuthInfo } from './authInfo';
 import { ScratchOrgCreateOptions, ScratchOrgCreateResult } from './scratchOrgCreate';
-export declare type OrganizationInformation = {
+export type OrganizationInformation = {
     Name: string;
     InstanceName: string;
     IsSandbox: boolean;
@@ -20,7 +19,7 @@ export declare enum OrgTypes {
 export interface StatusEvent {
     sandboxProcessObj: SandboxProcessObject;
     interval: number;
-    retries: number;
+    remainingWait: number;
     waitingOnAuth: boolean;
 }
 export interface ResultEvent {
@@ -36,7 +35,8 @@ export declare enum SandboxEvents {
     EVENT_STATUS = "status",
     EVENT_ASYNC_RESULT = "asyncResult",
     EVENT_RESULT = "result",
-    EVENT_AUTH = "auth"
+    EVENT_AUTH = "auth",
+    EVENT_RESUME = "resume"
 }
 export interface SandboxUserAuthResponse {
     authUserName: string;
@@ -44,7 +44,8 @@ export interface SandboxUserAuthResponse {
     instanceUrl: string;
     loginUrl: string;
 }
-export interface SandboxProcessObject {
+export declare function sandboxIsResumable(value: string): boolean;
+export type SandboxProcessObject = {
     Id: string;
     Status: string;
     SandboxName: string;
@@ -57,14 +58,27 @@ export interface SandboxProcessObject {
     Description?: string;
     ApexClassId?: string;
     EndDate?: string;
-}
-export declare type SandboxRequest = {
+};
+export type SandboxRequest = {
     SandboxName: string;
     LicenseType?: string;
+    /** Should match a SandboxInfoId, not a SandboxProcessId */
     SourceId?: string;
     Description?: string;
 };
-export declare type ScratchOrgRequest = Pick<ScratchOrgCreateOptions, 'connectedAppConsumerKey' | 'durationDays' | 'nonamespace' | 'noancestors' | 'wait' | 'retry' | 'apiversion' | 'definitionjson' | 'definitionfile' | 'orgConfig' | 'clientSecret'>;
+export type ResumeSandboxRequest = {
+    SandboxName?: string;
+    SandboxProcessObjId?: string;
+};
+export type ScratchOrgRequest = Omit<ScratchOrgCreateOptions, 'hubOrg'>;
+export type SandboxFields = {
+    sandboxOrgId: string;
+    prodOrgUsername: string;
+    sandboxName?: string;
+    sandboxUsername?: string;
+    sandboxProcessId?: string;
+    sandboxInfoId?: string;
+};
 /**
  * Provides a way to manage a locally authenticated Org.
  *
@@ -109,9 +123,34 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
      * @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: {
+    createSandbox(sandboxReq: SandboxRequest, options?: {
         wait?: Duration;
         interval?: Duration;
+        async?: boolean;
+    }): Promise<SandboxProcessObject>;
+    /**
+     *
+     * @param sandboxReq SandboxRequest options to create the sandbox with
+     * @param sourceSandboxName the name of the sandbox that your new sandbox will be based on
+     * @param options Wait: The amount of time to wait before timing out, defaults to 0, Interval: The time interval between polling defaults to 30 seconds
+     * @returns {SandboxProcessObject} the newly created sandbox process object
+     */
+    cloneSandbox(sandboxReq: SandboxRequest, sourceSandboxName: string, options: {
+        wait?: Duration;
+        interval?: Duration;
+    }): Promise<SandboxProcessObject>;
+    /**
+     * resume a sandbox creation 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 options Wait: The amount of time to wait (default: 30 minutes) before timing out,
+     * Interval: The time interval (default: 30 seconds) between polling
+     */
+    resumeSandbox(resumeSandboxRequest: ResumeSandboxRequest, options?: {
+        wait?: Duration;
+        interval?: Duration;
+        async?: boolean;
     }): Promise<SandboxProcessObject>;
     /**
      * Creates a scratchOrg
@@ -121,6 +160,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>.
      *
@@ -133,9 +183,7 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
      */
     retrieveOrgUsersConfig(): Promise<OrgUsersConfig>;
     /**
-     * Removes the scratch org config file at $HOME/.sfdx/[name].json, any project level org
-     * files, all user auth files for the org, matching default config settings, and any
-     * matching aliases.
+     * Cleans up all org related artifacts including users, sandbox config (if a sandbox), source tracking files, and auth file.
      *
      * @param throwWhenRemoveFails Determines if the call should throw an error or fail silently.
      */
@@ -148,9 +196,9 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
     /**
      * Check that this org is a scratch org by asking the dev hub if it knows about it.
      *
-     * **Throws** *{@link SfdxError}{ name: 'NotADevHubError' }* Not a Dev Hub.
+     * **Throws** *{@link SfError}{ name: 'NotADevHubError' }* Not a Dev Hub.
      *
-     * **Throws** *{@link SfdxError}{ name: 'NoResultsError' }* No results.
+     * **Throws** *{@link SfError}{ name: 'NoResultsError' }* No results.
      *
      * @param devHubUsernameOrAlias The username or alias of the dev hub org.
      */
@@ -196,6 +244,17 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
      * scratch org**. If you need accuracy, use the {@link Org.determineIfScratch} method.
      */
     isScratch(): boolean;
+    /**
+     * Returns `true` if the org uses source tracking.
+     * Side effect: updates files where the property doesn't currently exist
+     */
+    tracksSource(): Promise<boolean>;
+    /**
+     * Set the tracking property on the org's auth file
+     *
+     * @param value true or false (whether the org should use source tracking or not)
+     */
+    setTracksSource(value: boolean): Promise<void>;
     /**
      * Returns `true` if the org is a scratch org.
      *
@@ -253,23 +312,24 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
     /**
      * Removes a username from the user config for this object. For convenience `this` object is returned.
      *
-     * **Throws** *{@link SfdxError}{ name: 'MissingAuthInfoError' }* Auth info is missing.
+     * **Throws** *{@link SfError}{ name: 'MissingAuthInfoError' }* Auth info is missing.
      *
      * @param {AuthInfo | string} auth The AuthInfo containing the username to remove.
      */
     removeUsername(auth: AuthInfo | string): Promise<Org>;
     /**
-     * Sets the key/value pair in the sandbox config for this org. For convenience `this` object is returned.
-     *
+     * set the sandbox config related to this given org
      *
-     * @param {key} The key for this value
-     * @param {value} The value to save
+     * @param orgId {string} orgId of the sandbox
+     * @param config {SandboxFields} config of the sandbox
      */
-    setSandboxOrgConfigField(field: SandboxOrgConfig.Fields, value: string): Promise<Org>;
+    setSandboxConfig(orgId: string, config: SandboxFields): Promise<Org>;
     /**
-     * Returns an org config field. Returns undefined if the field is not set or invalid.
+     * get the sandbox config for the given orgId
+     *
+     * @param orgId {string} orgId of the sandbox
      */
-    getSandboxOrgConfigField(field: SandboxOrgConfig.Fields): Promise<any>;
+    getSandboxConfig(orgId: string): Promise<Nullable<SandboxFields>>;
     /**
      * Retrieves the highest api version that is supported by the target server instance. If the apiVersion configured for
      * Sfdx is greater than the one returned in this call an api version mismatch occurs. In the case of the CLI that
@@ -298,16 +358,66 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
     getFields(keys: Org.Fields[]): JsonMap;
     /**
      * Returns the JSForce connection for the org.
+     * side effect: If you pass it an apiVersion, it will set it on the Org
+     * so that future calls to getConnection() will also use that version.
+     *
+     * @param apiVersion The API version to use for the connection.
      */
-    getConnection(): Connection;
+    getConnection(apiVersion?: string): Connection;
+    supportsSourceTracking(): Promise<boolean>;
+    /**
+     * query SandboxProcess via sandbox name
+     *
+     * @param name SandboxName to query for
+     * @private
+     */
+    querySandboxProcessBySandboxName(name: string): Promise<SandboxProcessObject>;
+    /**
+     * query SandboxProcess via SandboxInfoId
+     *
+     * @param id SandboxInfoId to query for
+     * @private
+     */
+    querySandboxProcessBySandboxInfoId(id: string): Promise<SandboxProcessObject>;
+    /**
+     * query SandboxProcess via Id
+     *
+     * @param id SandboxProcessId to query for
+     * @private
+     */
+    querySandboxProcessById(id: string): Promise<SandboxProcessObject>;
     /**
      * Initialize async components.
      */
     protected init(): Promise<void>;
     /**
-     * **Throws** *{@link SfdxError}{ name: 'NotSupportedError' }* Throws an unsupported error.
+     * **Throws** *{@link SfError}{ name: 'NotSupportedError' }* Throws an unsupported error.
      */
     protected getDefaultOptions(): Org.Options;
+    private getLocalDataDir;
+    /**
+     * 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;
@@ -334,10 +444,6 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
      * Deletes the users config file
      */
     private removeUsersConfig;
-    /**
-     * @ignore
-     */
-    private retrieveSandboxOrgConfig;
     private manageDelete;
     /**
      * Remove the org users auth file.
@@ -345,38 +451,30 @@ export declare class Org extends AsyncOptionalCreatable<Org.Options> {
      * @param throwWhenRemoveFails true if manageDelete should throw or not if the deleted fails.
      */
     private removeUsers;
-    /**
-     * Remove an associate sandbox config.
-     *
-     * @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
+     * query SandboxProcess using supplied where clause
      *
-     * @param id SandboxInfoId to query for
+     * @param where clause to query for
      * @private
      */
     private querySandboxProcess;
     /**
      * determines if the sandbox has successfully been created
      *
-     * @param sandboxProcessObj sandbox signup progeress
+     * @param sandboxProcessObj sandbox signup progress
      * @private
      */
     private sandboxSignupComplete;
+    private validateWaitOptions;
+    /**
+     * removes source tracking files hosted in the project/.sf/orgs/<org id>/
+     *
+     * @private
+     */
+    private removeSourceTrackingFiles;
 }
 export declare namespace Org {
     /**
@@ -461,6 +559,11 @@ export declare namespace Org {
         /**
          * The snapshot used to create the scratch org.
          */
-        SNAPSHOT = "snapshot"
+        SNAPSHOT = "snapshot",
+        /**
+         * true: the org supports and wants source tracking
+         * false: the org opted out of tracking or can't support it
+         */
+        TRACKS_SOURCE = "tracksSource"
     }
 }