/**
 * Metadata associated with a service result.
 * Contains operational details that may be useful for debugging or logging.
 */
export type ServiceResultMetadata = {
    /** Additional context-specific metadata */
    [key: string]: unknown;
    /** Time taken for the operation in milliseconds */
    duration?: number;
    /** Strategy used (if multiple available) */
    strategyUsed?: string;
    /** Whether a fallback was used */
    fallbackUsed?: boolean;
    /** Original Salesforce error code if mapped from SF error */
    sfErrorCode?: string;
    /** Number of Salesforce API calls made during this operation */
    apiCallCount?: number;
};
/**
 * Generic service result wrapper following CLAUDE.md ServiceResult pattern.
 * All service and adapter methods should return this type for consistent handling.
 *
 * @template T The type of the data payload
 *
 * @example
 * ```typescript
 * // Success result
 * const success: ServiceResult<User[]> = {
 *   success: true,
 *   data: users,
 *   message: 'Found 10 users',
 *   metadata: { duration: 150 }
 * };
 *
 * // Failure result
 * const failure: ServiceResult<User[]> = {
 *   success: false,
 *   data: [],
 *   errorCode: 'E3102',
 *   message: 'Invalid SOQL query syntax'
 * };
 * ```
 */
export type ServiceResult<T> = {
    /** Whether the operation was successful */
    success: boolean;
    /** The operation result data */
    data: T;
    /** Error code for categorizing failures (see error code ranges in CLAUDE.md) */
    errorCode?: string;
    /** Human-readable message (error or success) */
    message?: string;
    /** Non-fatal warnings encountered during execution */
    warnings?: string[];
    /** Additional metadata about the operation */
    metadata?: ServiceResultMetadata;
};
/**
 * Creates a successful service result.
 *
 * @template T The type of the data payload
 * @param data - The result data
 * @param options - Optional message, warnings, and metadata
 * @returns A successful ServiceResult
 *
 * @example
 * ```typescript
 * return createSuccessResult(records, {
 *   message: `Found ${records.length} records`,
 *   metadata: { duration: Date.now() - startTime }
 * });
 * ```
 */
export declare function createSuccessResult<T>(data: T, options?: {
    message?: string;
    warnings?: string[];
    metadata?: ServiceResultMetadata;
}): ServiceResult<T>;
/**
 * Creates a failed service result.
 *
 * @template T The type of the data payload
 * @param data - The default/empty data for failed result
 * @param errorCode - The error code categorizing the failure
 * @param message - Human-readable error message (optional — omit to test nullish coalescing fallback)
 * @param options - Optional metadata
 * @returns A failed ServiceResult
 *
 * @example
 * ```typescript
 * return createFailureResult([], 'E3102', 'Invalid SOQL query syntax', {
 *   metadata: { sfErrorCode: 'INVALID_QUERY' }
 * });
 * ```
 */
export declare function createFailureResult<T>(data: T, errorCode: string, message?: string, options?: {
    metadata?: ServiceResultMetadata;
}): ServiceResult<T>;
/**
 * Creates a failed service result without data.
 *
 * Use when a failure occurs before any data is available (e.g., namespace guard
 * blocks a request, or validation fails before query execution). Avoids the
 * `undefined as unknown as T` cast pattern.
 *
 * @template T The type of the data payload (inferred from calling context)
 * @param errorCode - The error code categorizing the failure
 * @param message - Human-readable error message
 * @param options - Optional metadata
 * @returns A failed ServiceResult with data set to undefined
 */
export declare function createEmptyFailureResult<T>(errorCode: string, message?: string, options?: {
    metadata?: ServiceResultMetadata;
}): ServiceResult<T>;