1 | import { AsyncCreatable, Duration } from '@salesforce/kit';
|
2 | import { AnyJson, JsonMap, Optional } from '@salesforce/ts-types';
|
3 | import { ScratchOrgCreateOptions, ScratchOrgCreateResult } from './scratchOrgCreate';
|
4 | import { AuthFields, AuthInfo } from './authInfo';
|
5 | import { ConfigAggregator } from './config/configAggregator';
|
6 | import { OrgUsersConfig } from './config/orgUsersConfig';
|
7 | import { SandboxOrgConfig } from './config/sandboxOrgConfig';
|
8 | import { Connection } from './connection';
|
9 | export declare enum OrgTypes {
|
10 | Scratch = "scratch",
|
11 | Sandbox = "sandbox"
|
12 | }
|
13 | export interface StatusEvent {
|
14 | sandboxProcessObj: SandboxProcessObject;
|
15 | interval: number;
|
16 | retries: number;
|
17 | waitingOnAuth: boolean;
|
18 | }
|
19 | export interface ResultEvent {
|
20 | sandboxProcessObj: SandboxProcessObject;
|
21 | sandboxRes: SandboxUserAuthResponse;
|
22 | }
|
23 | export interface SandboxUserAuthRequest {
|
24 | sandboxName: string;
|
25 | clientId: string;
|
26 | callbackUrl: string;
|
27 | }
|
28 | export declare enum SandboxEvents {
|
29 | EVENT_STATUS = "status",
|
30 | EVENT_ASYNC_RESULT = "asyncResult",
|
31 | EVENT_RESULT = "result",
|
32 | EVENT_AUTH = "auth"
|
33 | }
|
34 | export interface SandboxUserAuthResponse {
|
35 | authUserName: string;
|
36 | authCode: string;
|
37 | instanceUrl: string;
|
38 | loginUrl: string;
|
39 | }
|
40 | export interface SandboxProcessObject {
|
41 | Id: string;
|
42 | Status: string;
|
43 | SandboxName: string;
|
44 | SandboxInfoId: string;
|
45 | LicenseType: string;
|
46 | CreatedDate: string;
|
47 | SandboxOrganization?: string;
|
48 | CopyProgress?: number;
|
49 | SourceId?: string;
|
50 | Description?: string;
|
51 | ApexClassId?: string;
|
52 | EndDate?: string;
|
53 | }
|
54 | export declare type SandboxRequest = {
|
55 | SandboxName: string;
|
56 | LicenseType?: string;
|
57 | SourceId?: string;
|
58 | Description?: string;
|
59 | };
|
60 | export declare type ScratchOrgRequest = Pick<ScratchOrgCreateOptions, 'connectedAppConsumerKey' | 'durationDays' | 'nonamespace' | 'noancestors' | 'wait' | 'retry' | 'apiversion' | 'definitionjson' | 'definitionfile' | 'orgConfig' | 'clientSecret'>;
|
61 | /**
|
62 | * Provides a way to manage a locally authenticated Org.
|
63 | *
|
64 | * **See** {@link AuthInfo}
|
65 | *
|
66 | * **See** {@link Connection}
|
67 | *
|
68 | * **See** {@link Aliases}
|
69 | *
|
70 | * **See** {@link Config}
|
71 | *
|
72 | * ```
|
73 | * // Email username
|
74 | * const org1: Org = await Org.create({ aliasOrUsername: 'foo@example.com' });
|
75 | * // The defaultusername config property
|
76 | * const org2: Org = await Org.create({});
|
77 | * // Full Connection
|
78 | * const org3: Org = await Org.create({
|
79 | * connection: await Connection.create({
|
80 | * authInfo: await AuthInfo.create({ username: 'username' })
|
81 | * })
|
82 | * });
|
83 | * ```
|
84 | *
|
85 | * **See** https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_cli_usernames_orgs.htm
|
86 | */
|
87 | export declare class Org extends AsyncCreatable<Org.Options> {
|
88 | private status;
|
89 | private configAggregator;
|
90 | private logger;
|
91 | private connection;
|
92 | private options;
|
93 | /**
|
94 | * @ignore
|
95 | */
|
96 | constructor(options: Org.Options);
|
97 | /**
|
98 | * create a sandbox from a production org
|
99 | * 'this' needs to be a production org with sandbox licenses available
|
100 | *
|
101 | * @param sandboxReq SandboxRequest options to create the sandbox with
|
102 | * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
|
103 | */
|
104 | createSandbox(sandboxReq: SandboxRequest, options: {
|
105 | wait?: Duration;
|
106 | interval?: Duration;
|
107 | }): Promise<SandboxProcessObject>;
|
108 | /**
|
109 | *
|
110 | * @param sandboxReq SandboxRequest options to create the sandbox with
|
111 | * @param sandboxName
|
112 | * @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
|
113 | * @returns {SandboxProcessObject} the newly created sandbox process object
|
114 | */
|
115 | cloneSandbox(sandboxReq: SandboxRequest, sandboxName: string, options: {
|
116 | wait?: Duration;
|
117 | interval?: Duration;
|
118 | }): Promise<SandboxProcessObject>;
|
119 | /**
|
120 | * Creates a scratchOrg
|
121 | * 'this' needs to be a valid dev-hub
|
122 | *
|
123 | * @param {options} ScratchOrgCreateOptions
|
124 | * @returns {ScratchOrgCreateResult}
|
125 | */
|
126 | scratchOrgCreate(options: ScratchOrgRequest): Promise<ScratchOrgCreateResult>;
|
127 | /**
|
128 | * Reports sandbox org creation status. If the org is ready, authenticates to the org.
|
129 | *
|
130 | * @param {sandboxname} string the sandbox name
|
131 | * @param options Wait: The amount of time to wait before timing out, Interval: The time interval between polling
|
132 | * @returns {SandboxProcessObject} the sandbox process object
|
133 | */
|
134 | sandboxStatus(sandboxname: string, options: {
|
135 | wait?: Duration;
|
136 | interval?: Duration;
|
137 | }): Promise<SandboxProcessObject>;
|
138 | /**
|
139 | * Clean all data files in the org's data path. Usually <workspace>/.sfdx/orgs/<username>.
|
140 | *
|
141 | * @param orgDataPath A relative path other than "orgs/".
|
142 | * @param throwWhenRemoveFails Should the remove org operations throw an error on failure?
|
143 | */
|
144 | cleanLocalOrgData(orgDataPath?: string, throwWhenRemoveFails?: boolean): Promise<void>;
|
145 | /**
|
146 | * @ignore
|
147 | */
|
148 | retrieveOrgUsersConfig(): Promise<OrgUsersConfig>;
|
149 | /**
|
150 | * Removes the scratch org config file at $HOME/.sfdx/[name].json, any project level org
|
151 | * files, all user auth files for the org, matching default config settings, and any
|
152 | * matching aliases.
|
153 | *
|
154 | * @param throwWhenRemoveFails Determines if the call should throw an error or fail silently.
|
155 | */
|
156 | remove(throwWhenRemoveFails?: boolean): Promise<void>;
|
157 | /**
|
158 | * Check if org is a sandbox org by checking its SandboxOrgConfig.
|
159 | *
|
160 | */
|
161 | isSandbox(): Promise<boolean>;
|
162 | /**
|
163 | * Check that this org is a scratch org by asking the dev hub if it knows about it.
|
164 | *
|
165 | * **Throws** *{@link SfdxError}{ name: 'NotADevHub' }* Not a Dev Hub.
|
166 | *
|
167 | * **Throws** *{@link SfdxError}{ name: 'NoResults' }* No results.
|
168 | *
|
169 | * @param devHubUsernameOrAlias The username or alias of the dev hub org.
|
170 | */
|
171 | checkScratchOrg(devHubUsernameOrAlias?: string): Promise<Partial<AuthFields>>;
|
172 | /**
|
173 | * Returns the Org object or null if this org is not affiliated with a Dev Hub (according to the local config).
|
174 | */
|
175 | getDevHubOrg(): Promise<Optional<Org>>;
|
176 | /**
|
177 | * Returns `true` if the org is a Dev Hub.
|
178 | *
|
179 | * **Note** This relies on a cached value in the auth file. If that property
|
180 | * is not cached, this method will **always return false even if the org is a
|
181 | * dev hub**. If you need accuracy, use the {@link Org.determineIfDevHubOrg} method.
|
182 | */
|
183 | isDevHubOrg(): boolean;
|
184 | /**
|
185 | * Will delete 'this' instance remotely and any files locally
|
186 | *
|
187 | * @param controllingOrg username or Org that 'this.devhub' or 'this.production' refers to. AKA a DevHub for a scratch org, or a Production Org for a sandbox
|
188 | */
|
189 | deleteFrom(controllingOrg: string | Org): Promise<void>;
|
190 | /**
|
191 | * Will delete 'this' instance remotely and any files locally
|
192 | */
|
193 | delete(): Promise<void>;
|
194 | /**
|
195 | * Returns `true` if the org is a Dev Hub.
|
196 | *
|
197 | * Use a cached value. If the cached value is not set, then check access to the
|
198 | * ScratchOrgInfo object to determine if the org is a dev hub.
|
199 | *
|
200 | * @param forceServerCheck Ignore the cached value and go straight to the server
|
201 | * which will be required if the org flips on the dev hub after the value is already
|
202 | * cached locally.
|
203 | */
|
204 | determineIfDevHubOrg(forceServerCheck?: boolean): Promise<boolean>;
|
205 | /**
|
206 | * Refreshes the auth for this org's instance by calling HTTP GET on the baseUrl of the connection object.
|
207 | */
|
208 | refreshAuth(): Promise<void>;
|
209 | /**
|
210 | * Reads and returns the content of all user auth files for this org as an array.
|
211 | */
|
212 | readUserAuthFiles(): Promise<AuthInfo[]>;
|
213 | /**
|
214 | * Adds a username to the user config for this org. For convenience `this` object is returned.
|
215 | *
|
216 | * ```
|
217 | * const org: Org = await Org.create({
|
218 | * connection: await Connection.create({
|
219 | * authInfo: await AuthInfo.create('foo@example.com')
|
220 | * })
|
221 | * });
|
222 | * const userAuth: AuthInfo = await AuthInfo.create({
|
223 | * username: 'bar@example.com'
|
224 | * });
|
225 | * await org.addUsername(userAuth);
|
226 | * ```
|
227 | *
|
228 | * @param {AuthInfo | string} auth The AuthInfo for the username to add.
|
229 | */
|
230 | addUsername(auth: AuthInfo | string): Promise<Org>;
|
231 | /**
|
232 | * Removes a username from the user config for this object. For convenience `this` object is returned.
|
233 | *
|
234 | * **Throws** *{@link SfdxError}{ name: 'MissingAuthInfo' }* Auth info is missing.
|
235 | *
|
236 | * @param {AuthInfo | string} auth The AuthInfo containing the username to remove.
|
237 | */
|
238 | removeUsername(auth: AuthInfo | string): Promise<Org>;
|
239 | /**
|
240 | * Sets the key/value pair in the sandbox config for this org. For convenience `this` object is returned.
|
241 | *
|
242 | *
|
243 | * @param {key} The key for this value
|
244 | * @param {value} The value to save
|
245 | */
|
246 | setSandboxOrgConfigField(field: SandboxOrgConfig.Fields, value: string): Promise<Org>;
|
247 | /**
|
248 | * Returns an org config field. Returns undefined if the field is not set or invalid.
|
249 | */
|
250 | getSandboxOrgConfigField(field: SandboxOrgConfig.Fields): Promise<any>;
|
251 | /**
|
252 | * Retrieves the highest api version that is supported by the target server instance. If the apiVersion configured for
|
253 | * Sfdx is greater than the one returned in this call an api version mismatch occurs. In the case of the CLI that
|
254 | * results in a warning.
|
255 | */
|
256 | retrieveMaxApiVersion(): Promise<string>;
|
257 | /**
|
258 | * Returns the admin username used to create the org.
|
259 | */
|
260 | getUsername(): Optional<string>;
|
261 | /**
|
262 | * Returns the orgId for this org.
|
263 | */
|
264 | getOrgId(): string;
|
265 | /**
|
266 | * Returns for the config aggregator.
|
267 | */
|
268 | getConfigAggregator(): ConfigAggregator;
|
269 | /**
|
270 | * Returns an org field. Returns undefined if the field is not set or invalid.
|
271 | */
|
272 | getField(key: Org.Fields): AnyJson;
|
273 | /**
|
274 | * Returns a map of requested fields.
|
275 | */
|
276 | getFields(keys: Org.Fields[]): JsonMap;
|
277 | /**
|
278 | * Returns the JSForce connection for the org.
|
279 | */
|
280 | getConnection(): Connection;
|
281 | /**
|
282 | * Initialize async components.
|
283 | */
|
284 | protected init(): Promise<void>;
|
285 | /**
|
286 | * **Throws** *{@link SfdxError} Throws and unsupported error.
|
287 | */
|
288 | protected getDefaultOptions(): Org.Options;
|
289 | /**
|
290 | * Query the sandbox for the SandboxProcessObject by sandbox name
|
291 | *
|
292 | * @param sandboxName The name of the sandbox to query
|
293 | * @returns {SandboxProcessObject} The SandboxProcessObject for the sandbox
|
294 | */
|
295 | private queryLatestSandboxProcessBySandboxName;
|
296 | /**
|
297 | * Gets the sandboxProcessObject and then polls for it to complete.
|
298 | *
|
299 | * @param sandboxProcessName sanbox process name
|
300 | * @param options { wait?: Duration; interval?: Duration }
|
301 | * @returns {SandboxProcessObject} The SandboxProcessObject for the sandbox
|
302 | */
|
303 | private authWithRetriesByName;
|
304 | /**
|
305 | * Polls the sandbox org for the sandboxProcessObject.
|
306 | *
|
307 | * @param sandboxProcessObj: The in-progress sandbox signup request
|
308 | * @param options { wait?: Duration; interval?: Duration }
|
309 | * @returns {SandboxProcessObject}
|
310 | */
|
311 | private authWithRetries;
|
312 | private queryProduction;
|
313 | /**
|
314 | * this method will delete the sandbox org from the production org and clean up any local files
|
315 | *
|
316 | * @param prodOrg - Production org associated with this sandbox
|
317 | * @private
|
318 | */
|
319 | private deleteSandbox;
|
320 | /**
|
321 | * If this Org is a scratch org, calling this method will delete the scratch org from the DevHub and clean up any local files
|
322 | *
|
323 | * @param devHub - optional DevHub Org of the to-be-deleted scratch org
|
324 | * @private
|
325 | */
|
326 | private deleteScratchOrg;
|
327 | /**
|
328 | * Returns a promise to delete an auth info file from the local file system and any related cache information for
|
329 | * this Org.. You don't want to call this method directly. Instead consider calling Org.remove()
|
330 | */
|
331 | private removeAuth;
|
332 | /**
|
333 | * Deletes the users config file
|
334 | */
|
335 | private removeUsersConfig;
|
336 | /**
|
337 | * @ignore
|
338 | */
|
339 | private retrieveSandboxOrgConfig;
|
340 | private manageDelete;
|
341 | /**
|
342 | * Remove the org users auth file.
|
343 | *
|
344 | * @param throwWhenRemoveFails true if manageDelete should throw or not if the deleted fails.
|
345 | */
|
346 | private removeUsers;
|
347 | /**
|
348 | * Remove an associate sandbox config.
|
349 | *
|
350 | * @param throwWhenRemoveFails true if manageDelete should throw or not if the deleted fails.
|
351 | */
|
352 | private removeSandboxConfig;
|
353 | private writeSandboxAuthFile;
|
354 | /**
|
355 | * Polls for the new sandbox to be created - and will write the associated auth files
|
356 | *
|
357 | * @private
|
358 | * @param options
|
359 | * sandboxProcessObj: The in-progress sandbox signup request
|
360 | * retries: the number of retries to poll for every 30s
|
361 | * shouldPoll: wait for polling, or just return
|
362 | * pollInterval: Duration to sleep between poll events, default 30 seconds
|
363 | */
|
364 | private pollStatusAndAuth;
|
365 | /**
|
366 | * query SandboxProcess via SandboxInfoId
|
367 | *
|
368 | * @param id SandboxInfoId to query for
|
369 | * @private
|
370 | */
|
371 | private querySandboxProcess;
|
372 | /**
|
373 | *
|
374 | * @param sandboxNameIn
|
375 | * @returns sandboxInfoId
|
376 | */
|
377 | private querySandboxInfoIdBySandboxName;
|
378 | /**
|
379 | * determines if the sandbox has successfully been created
|
380 | *
|
381 | * @param sandboxProcessObj sandbox signup progeress
|
382 | * @private
|
383 | */
|
384 | private sandboxSignupComplete;
|
385 | }
|
386 | export declare namespace Org {
|
387 | /**
|
388 | * Constructor Options for and Org.
|
389 | */
|
390 | interface Options {
|
391 | aliasOrUsername?: string;
|
392 | connection?: Connection;
|
393 | aggregator?: ConfigAggregator;
|
394 | isDevHub?: boolean;
|
395 | }
|
396 | /**
|
397 | * Scratch Org status.
|
398 | */
|
399 | enum Status {
|
400 | /**
|
401 | * The scratch org is active.
|
402 | */
|
403 | ACTIVE = "ACTIVE",
|
404 | /**
|
405 | * The scratch org has expired.
|
406 | */
|
407 | EXPIRED = "EXPIRED",
|
408 | /**
|
409 | * The org is a scratch Org but no dev hub is indicated.
|
410 | */
|
411 | UNKNOWN = "UNKNOWN",
|
412 | /**
|
413 | * The dev hub configuration is reporting an active Scratch org but the AuthInfo cannot be found.
|
414 | */
|
415 | MISSING = "MISSING"
|
416 | }
|
417 | /**
|
418 | * Org Fields.
|
419 | */
|
420 | enum Fields {
|
421 | /**
|
422 | * The org alias.
|
423 | */
|
424 | ALIAS = "alias",
|
425 | CREATED = "created",
|
426 | /**
|
427 | * The Salesforce instance the org was created on. e.g. `cs42`.
|
428 | */
|
429 | CREATED_ORG_INSTANCE = "createdOrgInstance",
|
430 | /**
|
431 | * The username of the dev hub org that created this org. Only populated for scratch orgs.
|
432 | */
|
433 | DEV_HUB_USERNAME = "devHubUsername",
|
434 | /**
|
435 | * The full url of the instance the org lives on.
|
436 | */
|
437 | INSTANCE_URL = "instanceUrl",
|
438 | /**
|
439 | * Is the current org a dev hub org. e.g. They have access to the `ScratchOrgInfo` object.
|
440 | */
|
441 | IS_DEV_HUB = "isDevHub",
|
442 | /**
|
443 | * The login url of the org. e.g. `https://login.salesforce.com` or `https://test.salesforce.com`.
|
444 | */
|
445 | LOGIN_URL = "loginUrl",
|
446 | /**
|
447 | * The org ID.
|
448 | */
|
449 | ORG_ID = "orgId",
|
450 | /**
|
451 | * The `OrgStatus` of the org.
|
452 | */
|
453 | STATUS = "status",
|
454 | /**
|
455 | * The snapshot used to create the scratch org.
|
456 | */
|
457 | SNAPSHOT = "snapshot"
|
458 | }
|
459 | }
|