@salesforce/core/lib/org/connection.d.ts

Core libraries to interact with SFDX projects, orgs, and APIs.

import { AsyncResult, DeployOptions, DeployResultLocator } from '@jsforce/jsforce-node/lib/api/metadata';
import { JsonMap, Optional } from '@salesforce/ts-types';
import { Connection as JSForceConnection, ConnectionConfig, HttpRequest, QueryOptions, QueryResult, Record, Schema } from '@jsforce/jsforce-node';
import { Tooling as JSForceTooling } from '@jsforce/jsforce-node/lib/api/tooling';
import { StreamPromise } from '@jsforce/jsforce-node/lib/util/promise';
import { ConfigAggregator } from '../config/configAggregator';
import { AuthFields, AuthInfo } from './authInfo';
export declare const SFDX_HTTP_HEADERS: {
    'content-type': string;
    'user-agent': string;
};
export declare const DNS_ERROR_NAME = "DomainNotFoundError";
export type DeployOptionsWithRest = Partial<DeployOptions> & {
    rest?: boolean;
};
export interface Tooling<S extends Schema = Schema> extends JSForceTooling<S> {
    _logger: any;
}
/**
 * Handles connections and requests to Salesforce Orgs.
 *
 * ```
 * // Uses latest API version
 * const connection = await Connection.create({
 *   authInfo: await AuthInfo.create({ username: 'myAdminUsername' })
 * });
 * connection.query('SELECT Name from Account');
 *
 * // Use different API version
 * connection.setApiVersion("42.0");
 * connection.query('SELECT Name from Account');
 * ```
 */
export declare class Connection<S extends Schema = Schema> extends JSForceConnection<S> {
    private logger;
    private options;
    private username;
    private hasResolved;
    private maxApiVersion;
    /**
     * Constructor
     * **Do not directly construct instances of this class -- use {@link Connection.create} instead.**
     *
     * @param options The options for the class instance.
     * @ignore
     */
    constructor(options: Connection.Options<S>);
    /**
     * Tooling api reference.
     */
    get tooling(): Tooling<S>;
    /**
     * Creates an instance of a Connection. Performs additional async initializations.
     *
     * @param options Constructor options.
     */
    static create<S extends Schema>(this: new (options: Connection.Options<S>) => Connection<S>, options: Connection.Options<S>): Promise<Connection<S>>;
    /**
     * Async initializer.
     */
    init(): Promise<void>;
    /**
     * deploy a zipped buffer from the SDRL with REST or SOAP
     *
     * @param zipInput data to deploy
     * @param options JSForce deploy options + a boolean for rest
     */
    deploy(zipInput: Buffer, options: DeployOptionsWithRest): Promise<DeployResultLocator<AsyncResult & Schema>>;
    /**
     * Send REST API request with given HTTP request info, with connected session information
     * and SFDX headers.
     *
     * @param request HTTP request object or URL to GET request.
     * @param options HTTP API request options.
     */
    request<R = unknown>(request: string | HttpRequest, options?: JsonMap): StreamPromise<R>;
    /**
     * The Force API base url for the instance.
     */
    baseUrl(): string;
    /**
     * Retrieves the highest api version that is supported by the target server instance.
     */
    retrieveMaxApiVersion(): Promise<string>;
    /**
     * Use the latest API version available on `this.instanceUrl`.
     */
    useLatestApiVersion(): Promise<void>;
    /**
     * Verify that instance has a reachable DNS entry, otherwise will throw error
     */
    isResolvable(): Promise<boolean>;
    /**
     * Get the API version used for all connection requests.
     */
    getApiVersion(): string;
    /**
     * Set the API version for all connection requests.
     *
     * **Throws** *{@link SfError}{ name: 'IncorrectAPIVersionError' }* Incorrect API version.
     *
     * @param version The API version.
     */
    setApiVersion(version: string): void;
    /**
     * Getter for AuthInfo.
     */
    getAuthInfo(): AuthInfo;
    /**
     * Getter for the AuthInfo fields.
     */
    getAuthInfoFields(): AuthFields;
    /**
     * Getter for the auth fields.
     */
    getConnectionOptions(): AuthFields;
    /**
     * Getter for the username of the Salesforce Org.
     */
    getUsername(): Optional<string>;
    /**
     * Returns true if this connection is using access token auth.
     */
    isUsingAccessToken(): boolean;
    /**
     * Normalize a Salesforce url to include a instance information.
     *
     * @param url Partial url.
     */
    normalizeUrl(url: string): string;
    /**
     * Executes a query and auto-fetches (i.e., "queryMore") all results.  This is especially
     * useful with large query result sizes, such as over 2000 records.  The default maximum
     * fetch size is 10,000 records. Modify this via the options argument.
     *
     * @param soql The SOQL string.
     * @param queryOptions The query options. NOTE: the autoFetch option will always be true.
     */
    autoFetchQuery<T extends Schema = S>(soql: string, queryOptions?: Partial<QueryOptions & {
        tooling: boolean;
    }>): Promise<QueryResult<T>>;
    /**
     * Executes a query using either standard REST or Tooling API, returning a single record.
     * Will throw if either zero records are found OR multiple records are found.
     *
     * @param soql The SOQL string.
     * @param options The query options.
     */
    singleRecordQuery<T extends Record>(soql: string, options?: SingleRecordQueryOptions): Promise<T>;
    /**
     * Executes a HEAD request on the baseUrl to force an auth refresh.
     * This is useful for the raw methods (request, requestRaw) that use the accessToken directly and don't handle refreshes.
     *
     * This method issues a request using the current access token to check if it is still valid.
     * If the request returns 200, no refresh happens, and we keep the token.
     * If it returns 401, jsforce will request a new token and set it in the connection instance.
     */
    refreshAuth(): Promise<void>;
    private getCachedApiVersion;
}
export declare const SingleRecordQueryErrors: {
    NoRecords: string;
    MultipleRecords: string;
};
export type SingleRecordQueryOptions = {
    tooling?: boolean;
    returnChoicesOnMultiple?: boolean;
    choiceField?: string;
};
export declare namespace Connection {
    /**
     * Connection Options.
     */
    type Options<S extends Schema> = {
        /**
         * AuthInfo instance.
         */
        authInfo: AuthInfo;
        /**
         * ConfigAggregator for getting defaults.
         */
        configAggregator?: ConfigAggregator;
        /**
         * Additional connection parameters.
         */
        connectionOptions?: ConnectionConfig<S>;
    };
}