@salesforce/agents/lib/connectionManager.d.ts

Client side APIs for working with Salesforce agents

import { Connection } from '@salesforce/core';
/**
 * Result of JWT validation
 */
export type JwtValidationResult = {
    isValid: boolean;
    hasRequiredFields: boolean;
    missingFields: string[];
    expiresAt?: Date;
    issuedAt?: Date;
    isExpired: boolean;
    subject?: string;
    issuer?: string;
    appId?: string;
    scopes?: string[];
};
/**
 * Manages JWT and standard connections for agent operations.
 *
 * This class provides:
 * - Automatic JWT creation and validation
 * - Separation of JWT connection (for SFAP) and standard connection (for org operations)
 * - Guard installation to prevent JWT token clobbering
 * - JWT validation utilities for debugging
 *
 * @example
 * ```typescript
 * const manager = await ConnectionManager.create(connection);
 *
 * // Get JWT connection for SFAP calls
 * const jwtConn = manager.getJwtConnection();
 * await jwtConn.request({ method: 'POST', url: '/authoring/scripts', ... });
 *
 * // Get standard connection for org queries
 * const standardConn = manager.getStandardConnection();
 * await standardConn.query('SELECT Id FROM User LIMIT 1');
 * ```
 */
export declare class ConnectionManager {
    private jwtConnection;
    private standardConnection;
    /**
     * Private constructor. Use ConnectionManager.create() instead.
     */
    private constructor();
    /**
     * Creates a new ConnectionManager instance.
     *
     * Builds two separate Connection objects derived from the username on the supplied
     * connection: a standard connection for org-instance operations (SOQL, tooling,
     * metadata) and a JWT-upgraded connection for SFAP API calls. The supplied
     * connection is read-only — it is never mutated.
     *
     * @param connection - The connection whose username is used to derive the new connections
     * @returns A new ConnectionManager instance
     * @throws {SfError} If JWT creation or validation fails, or if the connection has no username
     */
    static create(connection: Connection): Promise<ConnectionManager>;
    /**
     * Creates a fresh Connection from a username. Used for both the standard and JWT
     * connections so the caller's original Connection object is never mutated.
     */
    private static createConnectionFromUsername;
    /**
     * Upgrades a connection to a JWT connection for SFAP operations and validates the result.
     * The connection passed in is mutated (its accessToken is replaced with the JWT) — callers
     * must pass a fresh, isolated Connection rather than a connection they care about.
     */
    private static createAndValidateJwtConnection;
    /**
     * Validates that a token is a proper org JWT with required fields.
     *
     * @param token - The JWT token to validate
     * @returns Validation result with diagnostic information
     */
    private static validateJwt;
    /**
     * Gets the standard (non-JWT) connection for org-instance operations.
     * Use this for SOQL queries, metadata operations, tooling API, etc.
     *
     * @returns The standard connection
     */
    getStandardConnection(): Connection;
    /**
     * Gets the JWT connection for SFAP API calls.
     * Use this for all requests to api.salesforce.com/einstein/ai-agent endpoints.
     *
     * @returns The JWT connection
     */
    getJwtConnection(): Connection;
    /**
     * Inspects the current JWT and provides diagnostic information.
     * Useful for debugging and troubleshooting JWT-related issues.
     *
     * @returns JWT validation result with detailed diagnostic information
     */
    inspectJwt(): JwtValidationResult;
    /**
     * Refreshes the standard connection by clearing the access token and requesting a new one.
     * This is useful after agent operations to ensure subsequent org operations work correctly.
     *
     * @throws {SfError} If the refresh fails
     */
    refreshStandardConnection(): Promise<void>;
}
/**
 * Returns the ConnectionManager associated with the supplied Connection, creating one on
 * the first call. Subsequent calls with the same Connection return the cached manager.
 *
 * Different Connection objects — even for the same username — get distinct managers,
 * which is the desired behavior: the caller's connection identity is the unit of trust.
 *
 * @param connection The caller-supplied Connection used as the cache key
 * @returns A promise resolving to the manager for this connection
 */
export declare const managerFor: (connection: Connection) => Promise<ConnectionManager>;
/**
 * Test-only helper: pre-populate the cache so tests can substitute a fake manager
 * without exercising the real JWT bootstrap. Callers in production code should use
 * managerFor() instead.
 *
 * @internal
 */
export declare const setManagerForTesting: (connection: Connection, manager: ConnectionManager) => void;