import type { Connection } from '@salesforce/core';
/**
 * Query result structure from Salesforce.
 *
 * @template T The type of records in the result
 */
export type QueryResult<T> = {
    /** Whether the query is complete (no more records) */
    done: boolean;
    /** Total number of records matching the query */
    totalSize: number;
    /** Array of records returned */
    records: T[];
    /** Locator for next batch if done is false */
    nextRecordsUrl?: string;
};
/**
 * Picklist entry for picklist fields.
 */
export type PicklistEntry = {
    /** API value */
    value: string;
    /** Display label */
    label: string;
    /** Whether this is the default value */
    defaultValue: boolean;
    /** Whether this value is active */
    active: boolean;
};
/**
 * Child relationship for describe results.
 */
export type ChildRelationship = {
    /** Relationship name */
    relationshipName: string;
    /** Child object API name */
    childSObject: string;
    /** Field on child that references this object */
    field: string;
    /** Whether cascade delete is enabled */
    cascadeDelete: boolean;
};
/**
 * Record type info for describe results.
 */
export type RecordTypeInfo = {
    /** Record type ID */
    recordTypeId: string;
    /** Record type name */
    name: string;
    /** Developer name (may not be present in all versions) */
    developerName?: string;
    /** Whether this is the default record type */
    defaultRecordTypeMapping: boolean;
    /** Whether this is available */
    available: boolean;
    /** Whether this is the master record type */
    master: boolean;
};
/**
 * Describe result for a field.
 */
export type DescribeFieldResult = {
    /** API name of the field */
    name: string;
    /** User-friendly label */
    label: string;
    /** Field data type */
    type: string;
    /** Maximum length for text fields */
    length?: number;
    /** Precision for numeric fields */
    precision?: number;
    /** Scale for decimal fields */
    scale?: number;
    /** Whether this is a custom field */
    custom: boolean;
    /** Whether the field can be null */
    nillable: boolean;
    /** Whether the field is unique */
    unique: boolean;
    /** Whether this is an external ID field */
    externalId: boolean;
    /** Whether the field is a formula */
    calculated: boolean;
    /** Whether the field can be created */
    createable: boolean;
    /** Whether the field can be updated */
    updateable: boolean;
    /** Whether the field can be used in filters */
    filterable: boolean;
    /** Whether the field can be used in sorts */
    sortable: boolean;
    /** Default value if any */
    defaultValue?: unknown;
    /** Picklist values if picklist type */
    picklistValues?: PicklistEntry[];
    /** Reference to object(s) for lookup fields */
    referenceTo?: string[];
    /** Relationship name for lookup fields */
    relationshipName?: string;
};
/**
 * Describe result for a Salesforce object.
 */
export type DescribeSObjectResult = {
    /** API name of the object */
    name: string;
    /** User-friendly label */
    label: string;
    /** Plural label */
    labelPlural: string;
    /** Whether this is a custom object */
    custom: boolean;
    /** Whether records can be created */
    createable: boolean;
    /** Whether records can be updated */
    updateable: boolean;
    /** Whether records can be deleted */
    deletable: boolean;
    /** Whether the object can be queried */
    queryable: boolean;
    /** Whether the object is searchable */
    searchable: boolean;
    /** Field metadata */
    fields: DescribeFieldResult[];
    /** Child relationships */
    childRelationships?: ChildRelationship[];
    /** Record type infos */
    recordTypeInfos?: RecordTypeInfo[];
};
/**
 * Summary object info from global describe.
 */
export type DescribeGlobalSObjectResult = {
    /** API name of the object */
    name: string;
    /** User-friendly label */
    label: string;
    /** Plural label */
    labelPlural: string;
    /** Key prefix (3 character ID prefix) */
    keyPrefix: string | null;
    /** Whether this is a custom object */
    custom: boolean;
    /** Whether records can be created */
    createable: boolean;
    /** Whether records can be updated */
    updateable: boolean;
    /** Whether records can be deleted */
    deletable: boolean;
    /** Whether the object can be queried */
    queryable: boolean;
    /** Whether the object is searchable */
    searchable: boolean;
    /** Whether this is a Custom Setting (hierarchy or list type) */
    customSetting?: boolean;
};
/**
 * Global describe result containing all accessible objects.
 */
export type DescribeGlobalResult = {
    /** Maximum batch size for queries */
    maxBatchSize: number;
    /** Array of object metadata summaries */
    sobjects: DescribeGlobalSObjectResult[];
};
/**
 * Result of executing anonymous Apex.
 */
export type ExecuteAnonymousResult = {
    /** Whether execution was successful */
    success: boolean;
    /** Whether code was compiled successfully */
    compiled: boolean;
    /** Compilation problem description if compilation failed */
    compileProblem?: string;
    /** Line number of compilation error */
    line?: number;
    /** Column number of compilation error */
    column?: number;
    /** Exception message if runtime exception occurred */
    exceptionMessage?: string;
    /** Exception stack trace */
    exceptionStackTrace?: string;
};
/**
 * HTTP request configuration for custom API calls.
 */
export type HttpRequest = {
    /** Request URL (relative to instance URL) */
    url: string;
    /** HTTP method */
    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
    /** Request body for POST/PUT/PATCH */
    body?: unknown;
    /** Custom headers */
    headers?: Record<string, string>;
};
/**
 * Query builder for SObject find operations.
 *
 * Provides a fluent interface for building and executing queries.
 * Use the `limit()` method to constrain results, then `execute()` to run.
 *
 * @template T The SObject record type being queried
 *
 * @example
 * ```typescript
 * const accounts = await facade
 *   .sobject<Account>('Account')
 *   .find({ Type: 'Customer' }, ['Id', 'Name'])
 *   .limit(100)
 *   .execute();
 * ```
 */
export type ISObjectQueryBuilder<T> = {
    /**
     * Limits the number of records returned.
     *
     * @param count - Maximum number of records to return
     * @returns The query builder for method chaining
     */
    limit(count: number): ISObjectQueryBuilder<T>;
    /**
     * Executes the query and returns matching records.
     *
     * @returns Promise resolving to an array of matching records
     */
    execute(): Promise<T[]>;
};
/**
 * SObject API for record operations on a specific Salesforce object.
 *
 * Provides methods to describe object metadata and query records.
 *
 * @template T The SObject record type
 *
 * @example
 * ```typescript
 * const accountApi = facade.sobject<Account>('Account');
 * const metadata = await accountApi.describe();
 * const records = await accountApi.find({ Type: 'Customer' }).execute();
 * ```
 */
export type ISObjectApi<T> = {
    /**
     * Retrieves describe metadata for this SObject.
     *
     * @returns Promise resolving to the object's describe result
     */
    describe(): Promise<DescribeSObjectResult>;
    /**
     * Finds records matching the specified conditions.
     *
     * @param conditions - Field conditions to match (field name to value)
     * @param fields - Optional list of fields to retrieve (defaults to all)
     * @returns Query builder for further refinement and execution
     */
    find(conditions: Record<string, unknown>, fields?: string[]): ISObjectQueryBuilder<T>;
};
/**
 * Tooling API interface for metadata and development operations.
 *
 * Provides access to Salesforce Tooling API for querying metadata objects,
 * executing anonymous Apex, and CRUD operations on Tooling API entities.
 *
 * @example
 * ```typescript
 * // Query ApexClass metadata
 * const result = await facade.tooling.query<ApexClass>(
 *   "SELECT Id, Name FROM ApexClass WHERE Name LIKE 'Test%'"
 * );
 *
 * // Execute anonymous Apex
 * const execResult = await facade.tooling.executeAnonymous(
 *   'System.debug("Hello");'
 * );
 * ```
 */
export type IToolingApi = {
    /**
     * Executes a Tooling API SOQL query.
     *
     * @template T The expected record type in results
     * @param soql - The SOQL query string
     * @returns Promise resolving to query results with records
     */
    query<T>(soql: string): Promise<QueryResult<T>>;
    /**
     * Retrieves additional results for a paginated query.
     *
     * @template T The expected record type in results
     * @param locator - The nextRecordsUrl from a previous query result
     * @returns Promise resolving to the next batch of results
     */
    queryMore<T>(locator: string): Promise<QueryResult<T>>;
    /**
     * Executes anonymous Apex code.
     *
     * @param apex - The Apex code to execute
     * @returns Promise resolving to execution result with success/failure info
     */
    executeAnonymous(apex: string): Promise<ExecuteAnonymousResult>;
    /**
     * Creates a Tooling API record (e.g., TraceFlag, DebugLevel).
     *
     * @param type - The Tooling API object type name
     * @param record - The record data to create
     * @returns Promise resolving to creation result with id and success flag
     */
    create(type: string, record: Record<string, unknown>): Promise<{
        id: string;
        success: boolean;
    }>;
    /**
     * Deletes a Tooling API record.
     *
     * @param type - The Tooling API object type name
     * @param id - The record ID to delete
     * @returns Promise resolving to deletion result with id and success flag
     */
    destroy(type: string, id: string): Promise<{
        id: string;
        success: boolean;
    }>;
};
/**
 * Facade type for Salesforce Connection.
 *
 * This type wraps the @salesforce/core Connection class to provide
 * a testable, minimal surface for adapter implementations. The Connection
 * class has 400+ methods; this facade exposes only what adapters need.
 *
 * @example
 * ```typescript
 * // In production, wrap the actual connection
 * const facade = createConnectionFacade(connection);
 *
 * // In tests, use a mock
 * const mockFacade = createMockConnectionFacade();
 * ```
 */
export type IConnectionFacade = {
    /** Access Tooling API methods */
    tooling: IToolingApi;
    /** Get the API version being used */
    version: string;
    /** Get the access token for authentication */
    accessToken?: string;
    /** Get the instance URL for the Salesforce org */
    instanceUrl?: string;
    /** Execute a SOQL query */
    query<T>(soql: string): Promise<QueryResult<T>>;
    /** Query for additional results using nextRecordsUrl locator */
    queryMore<T>(locator: string): Promise<QueryResult<T>>;
    /** Get SObject API for a specific object */
    sobject<T>(name: string): ISObjectApi<T>;
    /** Make a custom HTTP request to the Salesforce API */
    request<T>(request: HttpRequest | string): Promise<T>;
    /** Get the current user's identity information */
    identity(): Promise<{
        user_id: string;
        organization_id: string;
        username: string;
    }>;
};
/**
 * Validation result for connection state.
 */
export type ConnectionValidationResult = {
    /** Whether the connection is valid */
    valid: boolean;
    /** Error code if invalid */
    errorCode?: string;
    /** Error message if invalid */
    errorMessage?: string;
};
/**
 * Validates that a connection has required properties for API calls.
 *
 * This checks that the connection has:
 * - An access token (authentication)
 * - An instance URL (target org)
 * - A version (API version)
 *
 * @param connection - The connection to validate
 * @returns Validation result indicating if connection is ready for use
 *
 * @example
 * ```typescript
 * const result = validateConnection(connection);
 * if (!result.valid) {
 *   throw new Error(`${result.errorCode}: ${result.errorMessage}`);
 * }
 * ```
 */
export declare function validateConnection(connection: Connection): ConnectionValidationResult;
/**
 * Creates a connection facade wrapper around a Salesforce Connection.
 *
 * @param connection - The @salesforce/core Connection instance
 * @param options - Optional configuration
 * @param options.skipValidation Skip connection validation (default: false)
 * @returns An IConnectionFacade wrapping the connection
 * @throws Error if connection validation fails and skipValidation is false
 *
 * @example
 * ```typescript
 * import { Connection } from '@salesforce/core';
 *
 * const org = await Org.create({ aliasOrUsername: 'myOrg' });
 * const connection = org.getConnection();
 * const facade = createConnectionFacade(connection);
 *
 * const result = await facade.query<Account>('SELECT Id, Name FROM Account LIMIT 10');
 * ```
 */
export declare function createConnectionFacade(connection: Connection, options?: {
    skipValidation?: boolean;
}): IConnectionFacade;
/**
 * Configuration options for debug connection facade.
 */
export type DebugConnectionFacadeOptions = {
    /** Enable debug logging for all API calls (default: false) */
    debug?: boolean;
};
/**
 * Creates a debug-wrapped connection facade that logs all API calls.
 *
 * When debug is enabled, wraps the facade to log:
 * - SOQL queries (truncated to 100 chars)
 * - Query results (record counts, timing)
 * - REST API calls (describe, request, identity)
 * - Tooling API calls (query, executeAnonymous)
 * - Errors when operations fail
 *
 * When debug is disabled (default), returns the original facade unchanged
 * with zero overhead.
 *
 * @param facade - The connection facade to wrap
 * @param options - Configuration options
 * @returns The facade, wrapped with logging if debug=true
 *
 * @example
 * ```typescript
 * // Without logging (production)
 * const facade = createDebugConnectionFacade(baseFacade);
 *
 * // With logging (debug mode)
 * const facade = createDebugConnectionFacade(baseFacade, { debug: true });
 * // Calls will log:
 * // [DEBUG] [ADAPTER] SOQL: query → SELECT Id FROM Account...
 * // [DEBUG] [ADAPTER] SOQL: complete → 100 records, 150ms
 * ```
 */
export declare function createDebugConnectionFacade(facade: IConnectionFacade, options?: DebugConnectionFacadeOptions): IConnectionFacade;