@salesforce/core 3.31.4 → 3.31.7

package/lib/org/authInfo.d.ts

@@ -1,344 +1,344 @@
-import { AsyncOptionalCreatable } from '@salesforce/kit';
-import { Nullable } from '@salesforce/ts-types';
-import { JwtOAuth2Config, OAuth2 } from 'jsforce';
-import { Connection } from './connection';
-import { Org } from './org';
-/**
- * Fields for authorization, org, and local information.
- */
-export declare type AuthFields = {
-    accessToken?: string;
-    alias?: string;
-    authCode?: string;
-    clientId?: string;
-    clientSecret?: string;
-    created?: string;
-    createdOrgInstance?: string;
-    devHubUsername?: string;
-    instanceUrl?: string;
-    instanceApiVersion?: string;
-    instanceApiVersionLastRetrieved?: string;
-    isDevHub?: boolean;
-    loginUrl?: string;
-    orgId?: string;
-    password?: string;
-    privateKey?: string;
-    refreshToken?: string;
-    scratchAdminUsername?: string;
-    snapshot?: string;
-    userId?: string;
-    username?: string;
-    usernames?: string[];
-    userProfileName?: string;
-    expirationDate?: string;
-    tracksSource?: boolean;
-    [Org.Fields.NAME]?: string;
-    [Org.Fields.INSTANCE_NAME]?: string;
-    [Org.Fields.NAMESPACE_PREFIX]?: Nullable<string>;
-    [Org.Fields.IS_SANDBOX]?: boolean;
-    [Org.Fields.IS_SCRATCH]?: boolean;
-    [Org.Fields.TRIAL_EXPIRATION_DATE]?: Nullable<string>;
-};
-export declare type OrgAuthorization = {
-    orgId: string;
-    username: string;
-    oauthMethod: 'jwt' | 'web' | 'token' | 'unknown';
-    aliases: Nullable<string[]>;
-    configs: Nullable<string[]>;
-    isScratchOrg?: boolean;
-    isDevHub?: boolean;
-    isSandbox?: boolean;
-    instanceUrl?: string;
-    accessToken?: string;
-    error?: string;
-    isExpired: boolean | 'unknown';
-};
-/**
- * Options for access token flow.
- */
-export interface AccessTokenOptions {
-    accessToken?: string;
-    loginUrl?: string;
-    instanceUrl?: string;
-}
-export declare type AuthSideEffects = {
-    alias?: string;
-    setDefault: boolean;
-    setDefaultDevHub: boolean;
-    setTracksSource?: boolean;
-};
-/**
- * A function to update a refresh token when the access token is expired.
- */
-export declare type RefreshFn = (conn: Connection, callback: (err: Nullable<Error>, accessToken?: string, res?: Record<string, unknown>) => Promise<void>) => Promise<void>;
-/**
- * Options for {@link Connection}.
- */
-export declare type ConnectionOptions = AuthFields & {
-    /**
-     * OAuth options.
-     */
-    oauth2?: Partial<JwtOAuth2Config>;
-    /**
-     * Refresh token callback.
-     */
-    refreshFn?: RefreshFn;
-};
-export declare const DEFAULT_CONNECTED_APP_INFO: {
-    clientId: string;
-    legacyClientId: string;
-    legacyClientSecret: string;
-};
-/**
- * Handles persistence and fetching of user authentication information using
- * JWT, OAuth, or refresh tokens. Sets up the refresh flows that jsForce will
- * use to keep tokens active. An AuthInfo can also be created with an access
- * token, but AuthInfos created with access tokens can't be persisted to disk.
- *
- * **See** [Authorization](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth.htm)
- *
- * **See** [Salesforce DX Usernames and Orgs](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_cli_usernames_orgs.htm)
- *
- * ```
- * // Creating a new authentication file.
- * const authInfo = await AuthInfo.create({
- *   username: myAdminUsername,
- *   oauth2Options: {
- *     loginUrl, authCode, clientId, clientSecret
- *   }
- * );
- * authInfo.save();
- *
- * // Creating an authorization info with an access token.
- * const authInfo = await AuthInfo.create({
- *   username: accessToken
- * });
- *
- * // Using an existing authentication file.
- * const authInfo = await AuthInfo.create({
- *   username: myAdminUsername
- * });
- *
- * // Using the AuthInfo
- * const connection = await Connection.create({ authInfo });
- * ```
- */
-export declare class AuthInfo extends AsyncOptionalCreatable<AuthInfo.Options> {
-    private usingAccessToken;
-    private logger;
-    private stateAggregator;
-    private username;
-    private options;
-    /**
-     * Constructor
-     * **Do not directly construct instances of this class -- use {@link AuthInfo.create} instead.**
-     *
-     * @param options The options for the class instance
-     */
-    constructor(options?: AuthInfo.Options);
-    /**
-     * Returns the default instance url
-     *
-     * @returns {string}
-     */
-    static getDefaultInstanceUrl(): string;
-    /**
-     * Get a list of all authorizations based on auth files stored in the global directory.
-     * One can supply a filter (see @param orgAuthFilter) and calling this function without
-     * a filter will return all authorizations.
-     *
-     * @param orgAuthFilter A predicate function that returns true for those org authorizations that are to be retained.
-     *
-     * @returns {Promise<OrgAuthorization[]>}
-     */
-    static listAllAuthorizations(orgAuthFilter?: (orgAuth: OrgAuthorization) => boolean): Promise<OrgAuthorization[]>;
-    /**
-     * Returns true if one or more authentications are persisted.
-     */
-    static hasAuthentications(): Promise<boolean>;
-    /**
-     * Get the authorization URL.
-     *
-     * @param options The options to generate the URL.
-     */
-    static getAuthorizationUrl(options: JwtOAuth2Config & {
-        scope?: string;
-    }, oauth2?: OAuth2): string;
-    /**
-     * Parse a sfdx auth url, usually obtained by `authInfo.getSfdxAuthUrl`.
-     *
-     * @example
-     * ```
-     * await AuthInfo.create(AuthInfo.parseSfdxAuthUrl(sfdxAuthUrl));
-     * ```
-     * @param sfdxAuthUrl
-     */
-    static parseSfdxAuthUrl(sfdxAuthUrl: string): Pick<AuthFields, 'clientId' | 'clientSecret' | 'refreshToken' | 'loginUrl'>;
-    /**
-     * Given a set of decrypted fields and an authInfo, determine if the org belongs to an available
-     * dev hub.
-     *
-     * @param fields
-     * @param orgAuthInfo
-     */
-    static identifyPossibleScratchOrgs(fields: AuthFields, orgAuthInfo: AuthInfo): Promise<void>;
-    /**
-     * Find all dev hubs available in the local environment.
-     */
-    static getDevHubAuthInfos(): Promise<OrgAuthorization[]>;
-    private static queryScratchOrg;
-    /**
-     * Get the username.
-     */
-    getUsername(): string;
-    /**
-     * Returns true if `this` is using the JWT flow.
-     */
-    isJwt(): boolean;
-    /**
-     * Returns true if `this` is using an access token flow.
-     */
-    isAccessTokenFlow(): boolean;
-    /**
-     * Returns true if `this` is using the oauth flow.
-     */
-    isOauth(): boolean;
-    /**
-     * Returns true if `this` is using the refresh token flow.
-     */
-    isRefreshTokenFlow(): boolean;
-    /**
-     * Updates the cache and persists the authentication fields (encrypted).
-     *
-     * @param authData New data to save.
-     */
-    save(authData?: AuthFields): Promise<AuthInfo>;
-    /**
-     * Update the authorization fields, encrypting sensitive fields, but do not persist.
-     * For convenience `this` object is returned.
-     *
-     * @param authData Authorization fields to update.
-     */
-    update(authData?: AuthFields): AuthInfo;
-    /**
-     * Get the auth fields (decrypted) needed to make a connection.
-     */
-    getConnectionOptions(): ConnectionOptions;
-    getClientId(): string;
-    getRedirectUri(): string;
-    /**
-     * Get the authorization fields.
-     *
-     * @param decrypt Decrypt the fields.
-     */
-    getFields(decrypt?: boolean): AuthFields;
-    /**
-     * Get the org front door (used for web based oauth flows)
-     */
-    getOrgFrontDoorUrl(): string;
-    /**
-     * Returns true if this org is using access token auth.
-     */
-    isUsingAccessToken(): boolean;
-    /**
-     * Get the SFDX Auth URL.
-     *
-     * **See** [SFDX Authorization](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_auth.htm#cli_reference_force_auth)
-     */
-    getSfdxAuthUrl(): string;
-    /**
-     * Convenience function to handle typical side effects encountered when dealing with an AuthInfo.
-     * Given the values supplied in parameter sideEffects, this function will set auth alias, default auth
-     * and default dev hub.
-     *
-     * @param sideEffects - instance of AuthSideEffects
-     */
-    handleAliasAndDefaultSettings(sideEffects: AuthSideEffects): Promise<void>;
-    /**
-     * Set the target-env (default) or the target-dev-hub to the alias if
-     * it exists otherwise to the username. Method will try to set the local
-     * config first but will default to global config if that fails.
-     *
-     * @param options
-     */
-    setAsDefault(options?: {
-        org?: boolean;
-        devHub?: boolean;
-    }): Promise<void>;
-    /**
-     * Sets the provided alias to the username
-     *
-     * @param alias alias to set
-     */
-    setAlias(alias: string): Promise<void>;
-    /**
-     * Initializes an instance of the AuthInfo class.
-     */
-    init(): Promise<void>;
-    private getInstanceUrl;
-    /**
-     * Initialize this AuthInfo instance with the specified options. If options are not provided, initialize it from cache
-     * or by reading from the persistence store. For convenience `this` object is returned.
-     *
-     * @param options Options to be used for creating an OAuth2 instance.
-     *
-     * **Throws** *{@link SfError}{ name: 'NamedOrgNotFoundError' }* Org information does not exist.
-     * @returns {Promise<AuthInfo>}
-     */
-    private initAuthOptions;
-    private loadDecryptedAuthFromConfig;
-    private isTokenOptions;
-    private refreshFn;
-    private readJwtKey;
-    private authJwt;
-    private tryJwtAuth;
-    private buildRefreshTokenConfig;
-    /**
-     * Performs an authCode exchange but the Oauth2 feature of jsforce is extended to include a code_challenge
-     *
-     * @param options The oauth options
-     * @param oauth2 The oauth2 extension that includes a code_challenge
-     */
-    private exchangeToken;
-    private retrieveUserInfo;
-    /**
-     * Given an error while getting the User object, handle different possibilities of response.body.
-     *
-     * @param response
-     * @private
-     */
-    private throwUserGetException;
-    /**
-     * Returns `true` if the org is a Dev Hub.
-     *
-     * Check access to the ScratchOrgInfo object to determine if the org is a dev hub.
-     */
-    private determineIfDevHub;
-}
-export declare namespace AuthInfo {
-    /**
-     * Constructor options for AuthInfo.
-     */
-    interface Options {
-        /**
-         * Org signup username.
-         */
-        username?: string;
-        /**
-         * OAuth options.
-         */
-        oauth2Options?: JwtOAuth2Config;
-        /**
-         * Options for the access token auth.
-         */
-        accessTokenOptions?: AccessTokenOptions;
-        oauth2?: OAuth2;
-        /**
-         * In certain situations, a new auth info wants to use the connected app
-         * information from another parent org. Typically for scratch org or sandbox
-         * creation.
-         */
-        parentUsername?: string;
-        isDevHub?: boolean;
-    }
-}
+import { AsyncOptionalCreatable } from '@salesforce/kit';
+import { Nullable } from '@salesforce/ts-types';
+import { JwtOAuth2Config, OAuth2 } from 'jsforce';
+import { Connection } from './connection';
+import { Org } from './org';
+/**
+ * Fields for authorization, org, and local information.
+ */
+export declare type AuthFields = {
+    accessToken?: string;
+    alias?: string;
+    authCode?: string;
+    clientId?: string;
+    clientSecret?: string;
+    created?: string;
+    createdOrgInstance?: string;
+    devHubUsername?: string;
+    instanceUrl?: string;
+    instanceApiVersion?: string;
+    instanceApiVersionLastRetrieved?: string;
+    isDevHub?: boolean;
+    loginUrl?: string;
+    orgId?: string;
+    password?: string;
+    privateKey?: string;
+    refreshToken?: string;
+    scratchAdminUsername?: string;
+    snapshot?: string;
+    userId?: string;
+    username?: string;
+    usernames?: string[];
+    userProfileName?: string;
+    expirationDate?: string;
+    tracksSource?: boolean;
+    [Org.Fields.NAME]?: string;
+    [Org.Fields.INSTANCE_NAME]?: string;
+    [Org.Fields.NAMESPACE_PREFIX]?: Nullable<string>;
+    [Org.Fields.IS_SANDBOX]?: boolean;
+    [Org.Fields.IS_SCRATCH]?: boolean;
+    [Org.Fields.TRIAL_EXPIRATION_DATE]?: Nullable<string>;
+};
+export declare type OrgAuthorization = {
+    orgId: string;
+    username: string;
+    oauthMethod: 'jwt' | 'web' | 'token' | 'unknown';
+    aliases: Nullable<string[]>;
+    configs: Nullable<string[]>;
+    isScratchOrg?: boolean;
+    isDevHub?: boolean;
+    isSandbox?: boolean;
+    instanceUrl?: string;
+    accessToken?: string;
+    error?: string;
+    isExpired: boolean | 'unknown';
+};
+/**
+ * Options for access token flow.
+ */
+export interface AccessTokenOptions {
+    accessToken?: string;
+    loginUrl?: string;
+    instanceUrl?: string;
+}
+export declare type AuthSideEffects = {
+    alias?: string;
+    setDefault: boolean;
+    setDefaultDevHub: boolean;
+    setTracksSource?: boolean;
+};
+/**
+ * A function to update a refresh token when the access token is expired.
+ */
+export declare type RefreshFn = (conn: Connection, callback: (err: Nullable<Error>, accessToken?: string, res?: Record<string, unknown>) => Promise<void>) => Promise<void>;
+/**
+ * Options for {@link Connection}.
+ */
+export declare type ConnectionOptions = AuthFields & {
+    /**
+     * OAuth options.
+     */
+    oauth2?: Partial<JwtOAuth2Config>;
+    /**
+     * Refresh token callback.
+     */
+    refreshFn?: RefreshFn;
+};
+export declare const DEFAULT_CONNECTED_APP_INFO: {
+    clientId: string;
+    legacyClientId: string;
+    legacyClientSecret: string;
+};
+/**
+ * Handles persistence and fetching of user authentication information using
+ * JWT, OAuth, or refresh tokens. Sets up the refresh flows that jsForce will
+ * use to keep tokens active. An AuthInfo can also be created with an access
+ * token, but AuthInfos created with access tokens can't be persisted to disk.
+ *
+ * **See** [Authorization](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth.htm)
+ *
+ * **See** [Salesforce DX Usernames and Orgs](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_cli_usernames_orgs.htm)
+ *
+ * ```
+ * // Creating a new authentication file.
+ * const authInfo = await AuthInfo.create({
+ *   username: myAdminUsername,
+ *   oauth2Options: {
+ *     loginUrl, authCode, clientId, clientSecret
+ *   }
+ * );
+ * authInfo.save();
+ *
+ * // Creating an authorization info with an access token.
+ * const authInfo = await AuthInfo.create({
+ *   username: accessToken
+ * });
+ *
+ * // Using an existing authentication file.
+ * const authInfo = await AuthInfo.create({
+ *   username: myAdminUsername
+ * });
+ *
+ * // Using the AuthInfo
+ * const connection = await Connection.create({ authInfo });
+ * ```
+ */
+export declare class AuthInfo extends AsyncOptionalCreatable<AuthInfo.Options> {
+    private usingAccessToken;
+    private logger;
+    private stateAggregator;
+    private username;
+    private options;
+    /**
+     * Constructor
+     * **Do not directly construct instances of this class -- use {@link AuthInfo.create} instead.**
+     *
+     * @param options The options for the class instance
+     */
+    constructor(options?: AuthInfo.Options);
+    /**
+     * Returns the default instance url
+     *
+     * @returns {string}
+     */
+    static getDefaultInstanceUrl(): string;
+    /**
+     * Get a list of all authorizations based on auth files stored in the global directory.
+     * One can supply a filter (see @param orgAuthFilter) and calling this function without
+     * a filter will return all authorizations.
+     *
+     * @param orgAuthFilter A predicate function that returns true for those org authorizations that are to be retained.
+     *
+     * @returns {Promise<OrgAuthorization[]>}
+     */
+    static listAllAuthorizations(orgAuthFilter?: (orgAuth: OrgAuthorization) => boolean): Promise<OrgAuthorization[]>;
+    /**
+     * Returns true if one or more authentications are persisted.
+     */
+    static hasAuthentications(): Promise<boolean>;
+    /**
+     * Get the authorization URL.
+     *
+     * @param options The options to generate the URL.
+     */
+    static getAuthorizationUrl(options: JwtOAuth2Config & {
+        scope?: string;
+    }, oauth2?: OAuth2): string;
+    /**
+     * Parse a sfdx auth url, usually obtained by `authInfo.getSfdxAuthUrl`.
+     *
+     * @example
+     * ```
+     * await AuthInfo.create(AuthInfo.parseSfdxAuthUrl(sfdxAuthUrl));
+     * ```
+     * @param sfdxAuthUrl
+     */
+    static parseSfdxAuthUrl(sfdxAuthUrl: string): Pick<AuthFields, 'clientId' | 'clientSecret' | 'refreshToken' | 'loginUrl'>;
+    /**
+     * Given a set of decrypted fields and an authInfo, determine if the org belongs to an available
+     * dev hub.
+     *
+     * @param fields
+     * @param orgAuthInfo
+     */
+    static identifyPossibleScratchOrgs(fields: AuthFields, orgAuthInfo: AuthInfo): Promise<void>;
+    /**
+     * Find all dev hubs available in the local environment.
+     */
+    static getDevHubAuthInfos(): Promise<OrgAuthorization[]>;
+    private static queryScratchOrg;
+    /**
+     * Get the username.
+     */
+    getUsername(): string;
+    /**
+     * Returns true if `this` is using the JWT flow.
+     */
+    isJwt(): boolean;
+    /**
+     * Returns true if `this` is using an access token flow.
+     */
+    isAccessTokenFlow(): boolean;
+    /**
+     * Returns true if `this` is using the oauth flow.
+     */
+    isOauth(): boolean;
+    /**
+     * Returns true if `this` is using the refresh token flow.
+     */
+    isRefreshTokenFlow(): boolean;
+    /**
+     * Updates the cache and persists the authentication fields (encrypted).
+     *
+     * @param authData New data to save.
+     */
+    save(authData?: AuthFields): Promise<AuthInfo>;
+    /**
+     * Update the authorization fields, encrypting sensitive fields, but do not persist.
+     * For convenience `this` object is returned.
+     *
+     * @param authData Authorization fields to update.
+     */
+    update(authData?: AuthFields): AuthInfo;
+    /**
+     * Get the auth fields (decrypted) needed to make a connection.
+     */
+    getConnectionOptions(): ConnectionOptions;
+    getClientId(): string;
+    getRedirectUri(): string;
+    /**
+     * Get the authorization fields.
+     *
+     * @param decrypt Decrypt the fields.
+     */
+    getFields(decrypt?: boolean): AuthFields;
+    /**
+     * Get the org front door (used for web based oauth flows)
+     */
+    getOrgFrontDoorUrl(): string;
+    /**
+     * Returns true if this org is using access token auth.
+     */
+    isUsingAccessToken(): boolean;
+    /**
+     * Get the SFDX Auth URL.
+     *
+     * **See** [SFDX Authorization](https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/cli_reference_force_auth.htm#cli_reference_force_auth)
+     */
+    getSfdxAuthUrl(): string;
+    /**
+     * Convenience function to handle typical side effects encountered when dealing with an AuthInfo.
+     * Given the values supplied in parameter sideEffects, this function will set auth alias, default auth
+     * and default dev hub.
+     *
+     * @param sideEffects - instance of AuthSideEffects
+     */
+    handleAliasAndDefaultSettings(sideEffects: AuthSideEffects): Promise<void>;
+    /**
+     * Set the target-env (default) or the target-dev-hub to the alias if
+     * it exists otherwise to the username. Method will try to set the local
+     * config first but will default to global config if that fails.
+     *
+     * @param options
+     */
+    setAsDefault(options?: {
+        org?: boolean;
+        devHub?: boolean;
+    }): Promise<void>;
+    /**
+     * Sets the provided alias to the username
+     *
+     * @param alias alias to set
+     */
+    setAlias(alias: string): Promise<void>;
+    /**
+     * Initializes an instance of the AuthInfo class.
+     */
+    init(): Promise<void>;
+    private getInstanceUrl;
+    /**
+     * Initialize this AuthInfo instance with the specified options. If options are not provided, initialize it from cache
+     * or by reading from the persistence store. For convenience `this` object is returned.
+     *
+     * @param options Options to be used for creating an OAuth2 instance.
+     *
+     * **Throws** *{@link SfError}{ name: 'NamedOrgNotFoundError' }* Org information does not exist.
+     * @returns {Promise<AuthInfo>}
+     */
+    private initAuthOptions;
+    private loadDecryptedAuthFromConfig;
+    private isTokenOptions;
+    private refreshFn;
+    private readJwtKey;
+    private authJwt;
+    private tryJwtAuth;
+    private buildRefreshTokenConfig;
+    /**
+     * Performs an authCode exchange but the Oauth2 feature of jsforce is extended to include a code_challenge
+     *
+     * @param options The oauth options
+     * @param oauth2 The oauth2 extension that includes a code_challenge
+     */
+    private exchangeToken;
+    private retrieveUserInfo;
+    /**
+     * Given an error while getting the User object, handle different possibilities of response.body.
+     *
+     * @param response
+     * @private
+     */
+    private throwUserGetException;
+    /**
+     * Returns `true` if the org is a Dev Hub.
+     *
+     * Check access to the ScratchOrgInfo object to determine if the org is a dev hub.
+     */
+    private determineIfDevHub;
+}
+export declare namespace AuthInfo {
+    /**
+     * Constructor options for AuthInfo.
+     */
+    interface Options {
+        /**
+         * Org signup username.
+         */
+        username?: string;
+        /**
+         * OAuth options.
+         */
+        oauth2Options?: JwtOAuth2Config;
+        /**
+         * Options for the access token auth.
+         */
+        accessTokenOptions?: AccessTokenOptions;
+        oauth2?: OAuth2;
+        /**
+         * In certain situations, a new auth info wants to use the connected app
+         * information from another parent org. Typically for scratch org or sandbox
+         * creation.
+         */
+        parentUsername?: string;
+        isDevHub?: boolean;
+    }
+}