Struct SalesforceRestClient 

pub struct SalesforceRestClient { /* private fields */ }

Salesforce REST API client.

Provides typed methods for all REST API operations:

• CRUD operations on SObjects
• SOQL queries with automatic pagination
• SOSL search
• Describe operations
• Composite API
• SObject Collections

Example

use sf_rest::SalesforceRestClient;

let client = SalesforceRestClient::new(
    "https://myorg.my.salesforce.com",
    "access_token_here",
)?;

// Query
let accounts: Vec<Account> = client.query_all("SELECT Id, Name FROM Account").await?;

// Create
let id = client.create("Account", &json!({"Name": "New Account"})).await?;

// Update
client.update("Account", &id, &json!({"Name": "Updated"})).await?;

// Delete
client.delete("Account", &id).await?;

Implementations

impl SalesforceRestClient

pub fn new( instance_url: impl Into<String>, access_token: impl Into<String>, ) -> Result<SalesforceRestClient, Error>

Create a new REST client with the given instance URL and access token.

Examples found in repository

examples/error_handling.rs (line 25)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing/logging if needed

    println!("=== Salesforce Error Handling Examples ===\n");

    let creds = get_credentials().await?;
    let client = SalesforceRestClient::new(creds.instance_url(), creds.access_token())?;

    // Error handling examples
    example_basic_error_handling(&client).await;
    example_retry_logic(&client).await;
    example_rate_limit_handling(&client).await;
    example_auth_error_detection(&client).await;
    example_error_categorization().await;

    println!("\n✓ All error handling examples completed!");

    Ok(())
}

examples/rest_crud.rs (line 44)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing for better logging and debugging
    tracing_subscriber::fmt::init();

    println!("=== Salesforce REST API CRUD Examples ===\n");

    // Get credentials (try SFDX first, then environment)
    let creds = get_credentials().await?;

    // Create REST client
    let client = SalesforceRestClient::new(creds.instance_url(), creds.access_token())?;

    // Run CRUD examples - showing BOTH patterns
    println!("--- Type-Safe Struct Pattern ---\n");
    let account_id = example_create_typed(&client).await?;
    example_read_typed(&client, &account_id).await?;
    example_update_typed(&client, &account_id).await?;

    println!("\n--- Dynamic JSON Pattern ---\n");
    let dynamic_id = example_create_dynamic(&client).await?;
    example_read_dynamic(&client, &dynamic_id).await?;

    // Clean up
    example_delete(&client, &account_id).await?;
    example_delete(&client, &dynamic_id).await?;

    // Advanced operations
    example_upsert(&client).await?;
    example_create_multiple(&client).await?;

    println!("\n✓ All CRUD examples completed successfully!");

    Ok(())
}

examples/queries.rs (line 72)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing for better observability
    tracing_subscriber::fmt::init();

    println!("=== Salesforce SOQL Query Examples ===\n");

    let creds = get_credentials().await?;
    let client = SalesforceRestClient::new(creds.instance_url(), creds.access_token())?;

    // RECOMMENDED: Use QueryBuilder (safe by default)
    println!("--- QueryBuilder Pattern (RECOMMENDED) ---\n");
    example_query_builder_typed(&client).await?;
    example_query_builder_dynamic(&client).await?;
    example_query_builder_advanced(&client).await?;

    // Alternative: Raw queries (less safe, but flexible)
    println!("\n--- Raw Query Patterns ---\n");
    example_basic_query_typed(&client).await?;
    example_basic_query_dynamic(&client).await?;

    // Manual escaping (NOT recommended, but shown for completeness)
    println!("\n--- Manual Escaping (NOT RECOMMENDED) ---\n");
    example_manual_escaping(&client).await?;

    // Advanced queries
    println!("\n--- Advanced Queries ---\n");
    example_relationship_query(&client).await?;
    example_aggregate_query(&client).await?;

    println!("\n✓ All query examples completed successfully!");

    Ok(())
}

pub fn with_config( instance_url: impl Into<String>, access_token: impl Into<String>, config: ClientConfig, ) -> Result<SalesforceRestClient, Error>

Create a new REST client with custom HTTP configuration.

pub fn from_client(client: SalesforceClient) -> SalesforceRestClient

Create a REST client from an existing SalesforceClient.

pub fn inner(&self) -> &SalesforceClient

Get the underlying SalesforceClient.

pub fn instance_url(&self) -> &str

Get the instance URL.

pub fn api_version(&self) -> &str

Get the API version.

pub fn with_api_version( self, version: impl Into<String>, ) -> SalesforceRestClient

Set the API version.

pub async fn describe_global(&self) -> Result<DescribeGlobalResult, Error>

Get a list of all SObjects available in the org.

This is equivalent to calling /services/data/vXX.0/sobjects/.

pub async fn describe_sobject( &self, sobject: &str, ) -> Result<DescribeSObjectResult, Error>

Get detailed metadata for a specific SObject.

This is equivalent to calling /services/data/vXX.0/sobjects/{sobject}/describe.

pub async fn create<T>( &self, sobject: &str, record: &T, ) -> Result<String, Error>

where T: Serialize,

Create a new record.

Returns the ID of the created record.

Examples found in repository

examples/error_handling.rs (line 223)

async fn create_account_with_context(
    client: &SalesforceRestClient,
    name: &str,
) -> Result<String, String> {
    let account = serde_json::json!({
        "Name": name
    });

    client.create("Account", &account).await.map_err(|e| {
        // Add context to the error
        format!("Failed to create account '{}': {}", name, e)
    })
}

examples/rest_crud.rs (line 84)

async fn example_create_typed(
    client: &SalesforceRestClient,
) -> Result<String, Box<dyn std::error::Error>> {
    println!("Example 1a: Create with Type-Safe Struct");
    println!("------------------------------------------");

    let account = Account {
        id: None,
        name: "Acme Corporation".to_string(),
        industry: Some("Technology".to_string()),
        phone: Some("+1-555-0100".to_string()),
        website: Some("https://acme.example.com".to_string()),
    };

    let id = client.create("Account", &account).await?;
    println!("✓ Created account with ID: {}", id);
    println!("  Benefits: Type safety, IDE support, compile-time checking");
    println!();

    Ok(id)
}

/// Example 1b: Create with dynamic JSON
async fn example_create_dynamic(
    client: &SalesforceRestClient,
) -> Result<String, Box<dyn std::error::Error>> {
    println!("Example 1b: Create with Dynamic JSON");
    println!("--------------------------------------");

    let account = serde_json::json!({
        "Name": "Dynamic Industries",
        "Industry": "Technology",
        "Phone": "+1-555-0200"
    });

    let id = client.create("Account", &account).await?;
    println!("✓ Created account with ID: {}", id);
    println!("  Benefits: Flexible, good for exploration/prototyping");
    println!();

    Ok(id)
}

pub async fn get<T>( &self, sobject: &str, id: &str, fields: Option<&[&str]>, ) -> Result<T, Error>

where T: DeserializeOwned,

Get a record by ID.

Optionally specify which fields to retrieve.

Examples found in repository

examples/rest_crud.rs (lines 122-126)

async fn example_read_typed(
    client: &SalesforceRestClient,
    account_id: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 2a: Read with Type-Safe Struct");
    println!("----------------------------------------");

    let account: Account = client
        .get(
            "Account",
            account_id,
            Some(&["Id", "Name", "Industry", "Phone", "Website"]),
        )
        .await?;

    println!("✓ Retrieved account:");
    println!("  ID: {:?}", account.id);
    println!("  Name: {}", account.name);
    println!("  Industry: {:?}", account.industry);
    println!("  Phone: {:?}", account.phone);
    println!("  Website: {:?}", account.website);
    println!();

    Ok(())
}

/// Example 2b: Read with dynamic JSON
async fn example_read_dynamic(
    client: &SalesforceRestClient,
    account_id: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 2b: Read with Dynamic JSON");
    println!("------------------------------------");

    let account: serde_json::Value = client
        .get(
            "Account",
            account_id,
            Some(&["Id", "Name", "Industry", "Phone"]),
        )
        .await?;

    println!("✓ Retrieved account:");
    println!("  ID: {}", account["Id"]);
    println!("  Name: {}", account["Name"]);
    println!("  Industry: {}", account["Industry"]);
    println!("  Phone: {}", account["Phone"]);
    println!();

    Ok(())
}

examples/error_handling.rs (line 46)

async fn example_basic_error_handling(client: &SalesforceRestClient) {
    println!("Example 1: Basic Error Handling");
    println!("--------------------------------");

    // Try to get a record that might not exist
    let result: Result<serde_json::Value, _> = client
        .get("Account", "001000000000000", None) // Invalid ID
        .await;

    match result {
        Ok(account) => {
            println!("✓ Found account: {:?}", account);
        }
        Err(e) => {
            println!("✗ Error occurred: {}", e);
            println!("  Error type: {:?}", e.kind);

            // Check if it's a "not found" error
            if matches!(e.kind, busbar_sf_rest::ErrorKind::Salesforce { .. }) {
                println!("  This is a Salesforce API error");
            }
        }
    }

    println!();
}

/// Example 2: Retry logic for transient errors
async fn example_retry_logic(client: &SalesforceRestClient) {
    println!("Example 2: Retry Logic");
    println!("----------------------");

    let max_retries = 3;
    let mut attempt = 0;

    loop {
        attempt += 1;
        println!("Attempt {}/{}", attempt, max_retries);

        // Try to query accounts
        let result: Result<Vec<serde_json::Value>, _> = client
            .query_all("SELECT Id, Name FROM Account LIMIT 10")
            .await;

        match result {
            Ok(accounts) => {
                println!("✓ Successfully retrieved {} accounts", accounts.len());
                break;
            }
            Err(e) => {
                println!("✗ Error: {}", e);

                // For demonstration, retry on any error (in production, check error type)
                if attempt < max_retries {
                    let backoff = Duration::from_secs(2u64.pow(attempt - 1));
                    println!("  Retrying after {:?}...", backoff);
                    sleep(backoff).await;
                } else {
                    println!("  Max retries reached");
                    break;
                }
            }
        }
    }

    println!();
}

/// Example 3: Rate limit handling
async fn example_rate_limit_handling(client: &SalesforceRestClient) {
    println!("Example 3: Rate Limit Handling");
    println!("-------------------------------");

    // Simulate checking org limits
    match client.limits().await {
        Ok(limits) => {
            println!("✓ Retrieved org limits");

            // Check API usage
            if let Some(daily_api) = limits.get("DailyApiRequests") {
                if let (Some(max), Some(remaining)) = (
                    daily_api.get("Max").and_then(|v| v.as_i64()),
                    daily_api.get("Remaining").and_then(|v| v.as_i64()),
                ) {
                    let usage_percent = ((max - remaining) as f64 / max as f64) * 100.0;
                    println!(
                        "  Daily API Usage: {:.1}% ({}/{})",
                        usage_percent,
                        max - remaining,
                        max
                    );

                    if usage_percent > 80.0 {
                        println!("  ⚠ Warning: API usage is above 80%!");
                    }
                }
            }
        }
        Err(e) => {
            println!("✗ Error retrieving limits: {}", e);
            println!("  Note: Check if rate limited or other error occurred");
        }
    }

    println!();
}

/// Example 4: Authentication error detection
async fn example_auth_error_detection(client: &SalesforceRestClient) {
    println!("Example 4: Authentication Error Detection");
    println!("------------------------------------------");

    // Try an operation (this will likely succeed with valid credentials)
    let result: Result<Vec<serde_json::Value>, _> =
        client.query_all("SELECT Id FROM Account LIMIT 1").await;

    match result {
        Ok(_) => {
            println!("✓ Authentication is valid");
        }
        Err(e) => {
            println!("✗ Error: {}", e);
            // Check error kind
            if matches!(e.kind, busbar_sf_rest::ErrorKind::Auth(_)) {
                println!("  This is an authentication error!");
                println!("  Action: Refresh access token or re-authenticate");
            }
        }
    }

    println!();
}

/// Example 5: Error categorization
async fn example_error_categorization() {
    println!("Example 5: Error Categorization");
    println!("--------------------------------");

    // Create different error types for demonstration
    let errors = vec![
        (
            "Rate Limited",
            ErrorKind::RateLimited {
                retry_after: Some(Duration::from_secs(30)),
            },
        ),
        ("Timeout", ErrorKind::Timeout),
        (
            "Authentication",
            ErrorKind::Authentication("Invalid token".to_string()),
        ),
        ("Not Found", ErrorKind::NotFound("Account".to_string())),
        (
            "Connection",
            ErrorKind::Connection("Network error".to_string()),
        ),
    ];

    for (name, error_kind) in errors {
        println!("\n{} Error:", name);
        println!("  Retryable: {}", error_kind.is_retryable());

        if let ErrorKind::RateLimited {
            retry_after: Some(duration),
        } = error_kind
        {
            println!("  Retry after: {:?}", duration);
        }
    }

    println!();
}

/// Example: Custom error handling with context
#[allow(dead_code)]
async fn create_account_with_context(
    client: &SalesforceRestClient,
    name: &str,
) -> Result<String, String> {
    let account = serde_json::json!({
        "Name": name
    });

    client.create("Account", &account).await.map_err(|e| {
        // Add context to the error
        format!("Failed to create account '{}': {}", name, e)
    })
}

/// Example: Error recovery strategies
#[allow(dead_code)]
async fn query_with_fallback(
    client: &SalesforceRestClient,
) -> Result<Vec<serde_json::Value>, Box<dyn std::error::Error>> {
    // Try primary query
    let result = client
        .query_all("SELECT Id, Name, CustomField__c FROM Account")
        .await;

    match result {
        Ok(accounts) => Ok(accounts),
        Err(e) => {
            // If field doesn't exist, try without it
            if let busbar_sf_rest::ErrorKind::Salesforce { error_code, .. } = &e.kind {
                if error_code == "INVALID_FIELD" {
                    println!("  CustomField__c doesn't exist, trying without it...");
                    return client
                        .query_all("SELECT Id, Name FROM Account")
                        .await
                        .map_err(Into::into);
                }
            }
            Err(e.into())
        }
    }
}

/// Example: Bulk error handling
#[allow(dead_code)]
async fn process_with_partial_failures(
    client: &SalesforceRestClient,
    account_ids: Vec<String>,
) -> (Vec<serde_json::Value>, Vec<String>) {
    let mut successful = Vec::new();
    let mut failed = Vec::new();

    for id in account_ids {
        match client.get::<serde_json::Value>("Account", &id, None).await {
            Ok(account) => successful.push(account),
            Err(e) => {
                eprintln!("Failed to get account {}: {}", id, e);
                failed.push(id);
            }
        }
    }

    (successful, failed)
}

pub async fn update<T>( &self, sobject: &str, id: &str, record: &T, ) -> Result<(), Error>

where T: Serialize,

Update a record.

Examples found in repository

examples/rest_crud.rs (line 180)

async fn example_update_typed(
    client: &SalesforceRestClient,
    account_id: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 3: Update Record");
    println!("------------------------");

    // For updates, dynamic JSON is often more convenient
    let updates = serde_json::json!({
        "Name": "Acme Corporation (Updated)",
        "Phone": "+1-555-0101"
    });

    client.update("Account", account_id, &updates).await?;
    println!("✓ Updated account {}", account_id);
    println!();

    Ok(())
}

pub async fn delete(&self, sobject: &str, id: &str) -> Result<(), Error>

Delete a record.

Examples found in repository

examples/rest_crud.rs (line 230)

async fn example_delete(
    client: &SalesforceRestClient,
    account_id: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 5: Delete Record");
    println!("------------------------");

    client.delete("Account", account_id).await?;
    println!("✓ Deleted account {}", account_id);
    println!();

    Ok(())
}

pub async fn upsert<T>( &self, sobject: &str, external_id_field: &str, external_id_value: &str, record: &T, ) -> Result<UpsertResult, Error>

where T: Serialize,

Upsert a record using an external ID field.

Creates the record if it doesn’t exist, updates it if it does.

Examples found in repository

examples/rest_crud.rs (line 202)

async fn example_upsert(client: &SalesforceRestClient) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 4: Upsert Record");
    println!("------------------------");

    let account = serde_json::json!({
        "Name": "Global Industries",
        "Industry": "Manufacturing"
    });

    // Use a custom external ID field (must exist in your org)
    // This example uses AccountNumber as an example
    let external_id = "EXT-12345";

    match client
        .upsert("Account", "AccountNumber", external_id, &account)
        .await
    {
        Ok(result) => {
            if result.created {
                println!("✓ Created new account: {}", result.id);
            } else {
                println!("✓ Updated existing account: {}", result.id);
            }
        }
        Err(e) => {
            println!("Note: Upsert requires an external ID field in your org");
            println!("  Error: {}", e);
        }
    }
    println!();

    Ok(())
}

pub async fn query<T>(&self, soql: &str) -> Result<QueryResult<T>, Error>

where T: DeserializeOwned,

Execute a SOQL query.

Returns the first page of results. Use query_all for automatic pagination.

Security

IMPORTANT: If you are including user-provided values in the WHERE clause, you MUST escape them to prevent SOQL injection attacks. Use the security utilities:

use busbar_sf_client::security::soql;

// WRONG - vulnerable to injection:
let query = format!("SELECT Id FROM Account WHERE Name = '{}'", user_input);

// CORRECT - properly escaped:
let safe_value = soql::escape_string(user_input);
let query = format!("SELECT Id FROM Account WHERE Name = '{}'", safe_value);

Examples found in repository

examples/queries.rs (line 190)

async fn example_basic_query_typed(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 1a: Type-Safe Query");
    println!("----------------------------");

    let query = "SELECT Id, Name, Industry FROM Account LIMIT 5";
    let result: busbar_sf_client::QueryResult<Account> = client.query(query).await?;

    println!(
        "✓ Found {} accounts (total: {})",
        result.records.len(),
        result.total_size
    );
    for account in &result.records {
        println!("  - {} (Industry: {:?})", account.name, account.industry);
    }
    println!("  Benefits: Type safety, field access without unwrapping");
    println!();

    Ok(())
}

/// Example 1b: Dynamic JSON query with proper serde_json patterns
async fn example_basic_query_dynamic(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 1b: Dynamic JSON Query");
    println!("-------------------------------");

    let query = "SELECT Id, Name, Industry FROM Account LIMIT 5";

    // Use HashMap for more ergonomic access than raw Value
    let result: busbar_sf_client::QueryResult<HashMap<String, serde_json::Value>> =
        client.query(query).await?;

    println!("✓ Found {} accounts", result.records.len());
    for account in &result.records {
        // Much more ergonomic than account["Name"].as_str().unwrap_or()
        let name = account
            .get("Name")
            .and_then(|v| v.as_str())
            .unwrap_or("Unknown");
        let industry = account
            .get("Industry")
            .and_then(|v| v.as_str())
            .unwrap_or("None");
        println!("  - {} (Industry: {})", name, industry);
    }
    println!("  Benefits: HashMap provides .get() method, no indexing panics");
    println!();

    Ok(())
}

/// Example 2: Automatic pagination with type safety
#[allow(dead_code)]
async fn example_query_pagination_typed(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 2: Pagination with Type Safety");
    println!("---------------------------------------");

    // query_all automatically handles pagination
    let query = "SELECT Id, Name FROM Account LIMIT 100";
    let accounts: Vec<Account> = client.query_all(query).await?;

    println!(
        "✓ Retrieved {} accounts (automatic pagination)",
        accounts.len()
    );
    println!();

    Ok(())
}

/// Example 3: Manual escaping - NOT RECOMMENDED but shown for completeness
///
/// WARNING: This approach is error-prone!
/// - Easy to forget to escape
/// - Easy to use wrong escape function (escape_string vs escape_like)
/// - Not safe by default
///
/// Prefer the SafeQueryBuilder pattern shown above!
async fn example_manual_escaping(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 3: Manual Escaping (NOT RECOMMENDED)");
    println!("---------------------------------------------");
    println!("⚠️  WARNING: Easy to forget! Use QueryBuilder instead.");
    println!();

    let user_input = "O'Brien's Company";
    let malicious_input = "'; DELETE FROM Account--";

    // Manual escaping - requires developer to remember!
    let safe_name = soql::escape_string(user_input);
    let query = format!("SELECT Id, Name FROM Account WHERE Name = '{}'", safe_name);

    let accounts: Vec<Account> = client.query_all(&query).await?;
    println!("  Found {} accounts", accounts.len());

    // Show what happens if you forget to escape (DON'T DO THIS!)
    let safe_malicious = soql::escape_string(malicious_input);
    println!("\n  Injection attempt:");
    println!("  Raw input:      {}", malicious_input);
    println!("  After escaping: {}", safe_malicious);
    println!("\n  ❌ Problem: Relies on developer remembering to escape");
    println!("  ✅ Solution: Use QueryBuilder that escapes automatically");
    println!();

    Ok(())
}

/// Example 4: Field validation
#[allow(dead_code)]
async fn example_field_validation(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 4: Field Validation");
    println!("---------------------------");

    // User-provided field names (could be malicious)
    let user_fields = vec![
        "Id",
        "Name",
        "Industry",
        "Bad'; DROP TABLE--", // Injection attempt
        "CustomField__c",
    ];

    // Filter to only safe field names
    let safe_fields: Vec<&str> = soql::filter_safe_fields(user_fields.iter().copied()).collect();

    println!("  Original fields: {:?}", user_fields);
    println!("  Safe fields:     {:?}", safe_fields);

    // Build SELECT clause with safe fields
    if let Some(select_clause) = soql::build_safe_select(&safe_fields) {
        let query = format!("SELECT {} FROM Account LIMIT 5", select_clause);

        // Use HashMap for dynamic field access
        let result: busbar_sf_client::QueryResult<HashMap<String, serde_json::Value>> =
            client.query(&query).await?;
        println!("✓ Retrieved {} records", result.records.len());
    } else {
        println!("✗ No safe fields to query");
    }

    println!();

    Ok(())
}

pub async fn query_all<T>(&self, soql: &str) -> Result<Vec<T>, Error>

where T: DeserializeOwned + Clone,

Execute a SOQL query and return all results (automatic pagination).

Security

IMPORTANT: Escape user-provided values with busbar_sf_client::security::soql::escape_string() to prevent SOQL injection attacks. See query() for examples.

Examples found in repository

examples/queries.rs (line 248)

async fn example_query_pagination_typed(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 2: Pagination with Type Safety");
    println!("---------------------------------------");

    // query_all automatically handles pagination
    let query = "SELECT Id, Name FROM Account LIMIT 100";
    let accounts: Vec<Account> = client.query_all(query).await?;

    println!(
        "✓ Retrieved {} accounts (automatic pagination)",
        accounts.len()
    );
    println!();

    Ok(())
}

/// Example 3: Manual escaping - NOT RECOMMENDED but shown for completeness
///
/// WARNING: This approach is error-prone!
/// - Easy to forget to escape
/// - Easy to use wrong escape function (escape_string vs escape_like)
/// - Not safe by default
///
/// Prefer the SafeQueryBuilder pattern shown above!
async fn example_manual_escaping(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 3: Manual Escaping (NOT RECOMMENDED)");
    println!("---------------------------------------------");
    println!("⚠️  WARNING: Easy to forget! Use QueryBuilder instead.");
    println!();

    let user_input = "O'Brien's Company";
    let malicious_input = "'; DELETE FROM Account--";

    // Manual escaping - requires developer to remember!
    let safe_name = soql::escape_string(user_input);
    let query = format!("SELECT Id, Name FROM Account WHERE Name = '{}'", safe_name);

    let accounts: Vec<Account> = client.query_all(&query).await?;
    println!("  Found {} accounts", accounts.len());

    // Show what happens if you forget to escape (DON'T DO THIS!)
    let safe_malicious = soql::escape_string(malicious_input);
    println!("\n  Injection attempt:");
    println!("  Raw input:      {}", malicious_input);
    println!("  After escaping: {}", safe_malicious);
    println!("\n  ❌ Problem: Relies on developer remembering to escape");
    println!("  ✅ Solution: Use QueryBuilder that escapes automatically");
    println!();

    Ok(())
}

/// Example 4: Field validation
#[allow(dead_code)]
async fn example_field_validation(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 4: Field Validation");
    println!("---------------------------");

    // User-provided field names (could be malicious)
    let user_fields = vec![
        "Id",
        "Name",
        "Industry",
        "Bad'; DROP TABLE--", // Injection attempt
        "CustomField__c",
    ];

    // Filter to only safe field names
    let safe_fields: Vec<&str> = soql::filter_safe_fields(user_fields.iter().copied()).collect();

    println!("  Original fields: {:?}", user_fields);
    println!("  Safe fields:     {:?}", safe_fields);

    // Build SELECT clause with safe fields
    if let Some(select_clause) = soql::build_safe_select(&safe_fields) {
        let query = format!("SELECT {} FROM Account LIMIT 5", select_clause);

        // Use HashMap for dynamic field access
        let result: busbar_sf_client::QueryResult<HashMap<String, serde_json::Value>> =
            client.query(&query).await?;
        println!("✓ Retrieved {} records", result.records.len());
    } else {
        println!("✗ No safe fields to query");
    }

    println!();

    Ok(())
}

/// Example 7: Relationship query
async fn example_relationship_query(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 7: Relationship Query");
    println!("-----------------------------");

    let query =
        "SELECT Id, Name, Email, Account.Name FROM Contact WHERE Account.Name != null LIMIT 5";

    let contacts: Vec<serde_json::Value> = client.query_all(query).await?;

    println!("✓ Found {} contacts with accounts", contacts.len());
    for contact in &contacts {
        let name = contact
            .get("Name")
            .and_then(|v| v.as_str())
            .unwrap_or("Unknown");
        let id = contact
            .get("Id")
            .and_then(|v| v.as_str())
            .unwrap_or("Unknown");
        if let Some(account) = contact.get("Account") {
            if let Some(account_name) = account.get("Name").and_then(|v| v.as_str()) {
                println!("  - {} ({}) @ {}", name, id, account_name);
            }
        }
    }
    println!();

    Ok(())
}

/// Example 8: Aggregate query
async fn example_aggregate_query(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 8: Aggregate Query");
    println!("--------------------------");

    let query = "SELECT Industry, COUNT(Id) total FROM Account WHERE Industry != null GROUP BY Industry ORDER BY COUNT(Id) DESC LIMIT 5";

    let results: Vec<serde_json::Value> = client.query_all(query).await?;

    println!("✓ Top {} industries:", results.len());
    for result in &results {
        let industry = result
            .get("Industry")
            .and_then(|v| v.as_str())
            .unwrap_or("Unknown");
        let total = result.get("total").and_then(|v| v.as_i64()).unwrap_or(0);
        println!("  - {}: {} accounts", industry, total);
    }
    println!();

    Ok(())
}

examples/error_handling.rs (line 81)

async fn example_retry_logic(client: &SalesforceRestClient) {
    println!("Example 2: Retry Logic");
    println!("----------------------");

    let max_retries = 3;
    let mut attempt = 0;

    loop {
        attempt += 1;
        println!("Attempt {}/{}", attempt, max_retries);

        // Try to query accounts
        let result: Result<Vec<serde_json::Value>, _> = client
            .query_all("SELECT Id, Name FROM Account LIMIT 10")
            .await;

        match result {
            Ok(accounts) => {
                println!("✓ Successfully retrieved {} accounts", accounts.len());
                break;
            }
            Err(e) => {
                println!("✗ Error: {}", e);

                // For demonstration, retry on any error (in production, check error type)
                if attempt < max_retries {
                    let backoff = Duration::from_secs(2u64.pow(attempt - 1));
                    println!("  Retrying after {:?}...", backoff);
                    sleep(backoff).await;
                } else {
                    println!("  Max retries reached");
                    break;
                }
            }
        }
    }

    println!();
}

/// Example 3: Rate limit handling
async fn example_rate_limit_handling(client: &SalesforceRestClient) {
    println!("Example 3: Rate Limit Handling");
    println!("-------------------------------");

    // Simulate checking org limits
    match client.limits().await {
        Ok(limits) => {
            println!("✓ Retrieved org limits");

            // Check API usage
            if let Some(daily_api) = limits.get("DailyApiRequests") {
                if let (Some(max), Some(remaining)) = (
                    daily_api.get("Max").and_then(|v| v.as_i64()),
                    daily_api.get("Remaining").and_then(|v| v.as_i64()),
                ) {
                    let usage_percent = ((max - remaining) as f64 / max as f64) * 100.0;
                    println!(
                        "  Daily API Usage: {:.1}% ({}/{})",
                        usage_percent,
                        max - remaining,
                        max
                    );

                    if usage_percent > 80.0 {
                        println!("  ⚠ Warning: API usage is above 80%!");
                    }
                }
            }
        }
        Err(e) => {
            println!("✗ Error retrieving limits: {}", e);
            println!("  Note: Check if rate limited or other error occurred");
        }
    }

    println!();
}

/// Example 4: Authentication error detection
async fn example_auth_error_detection(client: &SalesforceRestClient) {
    println!("Example 4: Authentication Error Detection");
    println!("------------------------------------------");

    // Try an operation (this will likely succeed with valid credentials)
    let result: Result<Vec<serde_json::Value>, _> =
        client.query_all("SELECT Id FROM Account LIMIT 1").await;

    match result {
        Ok(_) => {
            println!("✓ Authentication is valid");
        }
        Err(e) => {
            println!("✗ Error: {}", e);
            // Check error kind
            if matches!(e.kind, busbar_sf_rest::ErrorKind::Auth(_)) {
                println!("  This is an authentication error!");
                println!("  Action: Refresh access token or re-authenticate");
            }
        }
    }

    println!();
}

/// Example 5: Error categorization
async fn example_error_categorization() {
    println!("Example 5: Error Categorization");
    println!("--------------------------------");

    // Create different error types for demonstration
    let errors = vec![
        (
            "Rate Limited",
            ErrorKind::RateLimited {
                retry_after: Some(Duration::from_secs(30)),
            },
        ),
        ("Timeout", ErrorKind::Timeout),
        (
            "Authentication",
            ErrorKind::Authentication("Invalid token".to_string()),
        ),
        ("Not Found", ErrorKind::NotFound("Account".to_string())),
        (
            "Connection",
            ErrorKind::Connection("Network error".to_string()),
        ),
    ];

    for (name, error_kind) in errors {
        println!("\n{} Error:", name);
        println!("  Retryable: {}", error_kind.is_retryable());

        if let ErrorKind::RateLimited {
            retry_after: Some(duration),
        } = error_kind
        {
            println!("  Retry after: {:?}", duration);
        }
    }

    println!();
}

/// Example: Custom error handling with context
#[allow(dead_code)]
async fn create_account_with_context(
    client: &SalesforceRestClient,
    name: &str,
) -> Result<String, String> {
    let account = serde_json::json!({
        "Name": name
    });

    client.create("Account", &account).await.map_err(|e| {
        // Add context to the error
        format!("Failed to create account '{}': {}", name, e)
    })
}

/// Example: Error recovery strategies
#[allow(dead_code)]
async fn query_with_fallback(
    client: &SalesforceRestClient,
) -> Result<Vec<serde_json::Value>, Box<dyn std::error::Error>> {
    // Try primary query
    let result = client
        .query_all("SELECT Id, Name, CustomField__c FROM Account")
        .await;

    match result {
        Ok(accounts) => Ok(accounts),
        Err(e) => {
            // If field doesn't exist, try without it
            if let busbar_sf_rest::ErrorKind::Salesforce { error_code, .. } = &e.kind {
                if error_code == "INVALID_FIELD" {
                    println!("  CustomField__c doesn't exist, trying without it...");
                    return client
                        .query_all("SELECT Id, Name FROM Account")
                        .await
                        .map_err(Into::into);
                }
            }
            Err(e.into())
        }
    }
}

pub async fn query_all_including_deleted<T>( &self, soql: &str, ) -> Result<QueryResult<T>, Error>

where T: DeserializeOwned,

Execute a SOQL query including deleted/archived records.

Security

IMPORTANT: Escape user-provided values with busbar_sf_client::security::soql::escape_string() to prevent SOQL injection attacks. See query() for examples.

pub async fn query_more<T>( &self, next_records_url: &str, ) -> Result<QueryResult<T>, Error>

where T: DeserializeOwned,

Fetch the next page of query results.

pub async fn search<T>(&self, sosl: &str) -> Result<SearchResult<T>, Error>

where T: DeserializeOwned,

Execute a SOSL search.

Security

IMPORTANT: If you are including user-provided values in the search term, you MUST escape them. Use busbar_sf_client::security::soql::escape_string() for string values in SOSL queries.

pub async fn composite( &self, request: &CompositeRequest, ) -> Result<CompositeResponse, Error>

Execute a composite request with multiple subrequests.

The composite API allows up to 25 subrequests in a single API call.

pub async fn create_multiple<T>( &self, sobject: &str, records: &[T], all_or_none: bool, ) -> Result<Vec<CollectionResult>, Error>

where T: Serialize,

Create multiple records in a single request (up to 200).

Examples found in repository

examples/rest_crud.rs (line 270)

async fn example_create_multiple(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 6: Create Multiple Records");
    println!("-----------------------------------");

    let accounts = vec![
        Account {
            id: None,
            name: "Tech Startup Inc".to_string(),
            industry: Some("Technology".to_string()),
            phone: None,
            website: Some("https://techstartup.example".to_string()),
        },
        Account {
            id: None,
            name: "Retail Giant LLC".to_string(),
            industry: Some("Retail".to_string()),
            phone: None,
            website: Some("https://retailgiant.example".to_string()),
        },
        Account {
            id: None,
            name: "Finance Corp".to_string(),
            industry: Some("Finance".to_string()),
            phone: None,
            website: None,
        },
    ];

    // Create up to 200 records at once
    // all_or_none: true means either all succeed or all fail
    let results = client.create_multiple("Account", &accounts, true).await?;

    println!("✓ Created {} accounts", results.len());
    for (i, result) in results.iter().enumerate() {
        if result.success {
            let id = result.id.as_deref().unwrap_or("Unknown");
            println!("  Account {}: {} - ID: {}", i + 1, accounts[i].name, id);
        } else {
            println!("  Account {}: Failed - {:?}", i + 1, result.errors);
        }
    }

    // Clean up test data
    let ids: Vec<&str> = results.iter().filter_map(|r| r.id.as_deref()).collect();
    if !ids.is_empty() {
        let _ = client.delete_multiple(&ids, false).await;
        println!("✓ Cleaned up {} test accounts", ids.len());
    }

    println!();

    Ok(())
}

pub async fn update_multiple<T>( &self, sobject: &str, records: &[(String, T)], all_or_none: bool, ) -> Result<Vec<CollectionResult>, Error>

where T: Serialize,

Update multiple records in a single request (up to 200).

pub async fn delete_multiple( &self, ids: &[&str], all_or_none: bool, ) -> Result<Vec<CollectionResult>, Error>

Delete multiple records in a single request (up to 200).

Examples found in repository

examples/rest_crud.rs (line 285)

async fn example_create_multiple(
    client: &SalesforceRestClient,
) -> Result<(), Box<dyn std::error::Error>> {
    println!("Example 6: Create Multiple Records");
    println!("-----------------------------------");

    let accounts = vec![
        Account {
            id: None,
            name: "Tech Startup Inc".to_string(),
            industry: Some("Technology".to_string()),
            phone: None,
            website: Some("https://techstartup.example".to_string()),
        },
        Account {
            id: None,
            name: "Retail Giant LLC".to_string(),
            industry: Some("Retail".to_string()),
            phone: None,
            website: Some("https://retailgiant.example".to_string()),
        },
        Account {
            id: None,
            name: "Finance Corp".to_string(),
            industry: Some("Finance".to_string()),
            phone: None,
            website: None,
        },
    ];

    // Create up to 200 records at once
    // all_or_none: true means either all succeed or all fail
    let results = client.create_multiple("Account", &accounts, true).await?;

    println!("✓ Created {} accounts", results.len());
    for (i, result) in results.iter().enumerate() {
        if result.success {
            let id = result.id.as_deref().unwrap_or("Unknown");
            println!("  Account {}: {} - ID: {}", i + 1, accounts[i].name, id);
        } else {
            println!("  Account {}: Failed - {:?}", i + 1, result.errors);
        }
    }

    // Clean up test data
    let ids: Vec<&str> = results.iter().filter_map(|r| r.id.as_deref()).collect();
    if !ids.is_empty() {
        let _ = client.delete_multiple(&ids, false).await;
        println!("✓ Cleaned up {} test accounts", ids.len());
    }

    println!();

    Ok(())
}

pub async fn get_multiple<T>( &self, sobject: &str, ids: &[&str], fields: &[&str], ) -> Result<Vec<T>, Error>

where T: DeserializeOwned,

Get multiple records by ID in a single request (up to 2000).

pub async fn limits(&self) -> Result<Value, Error>

Get API limits for the org.

Examples found in repository

examples/error_handling.rs (line 114)

async fn example_rate_limit_handling(client: &SalesforceRestClient) {
    println!("Example 3: Rate Limit Handling");
    println!("-------------------------------");

    // Simulate checking org limits
    match client.limits().await {
        Ok(limits) => {
            println!("✓ Retrieved org limits");

            // Check API usage
            if let Some(daily_api) = limits.get("DailyApiRequests") {
                if let (Some(max), Some(remaining)) = (
                    daily_api.get("Max").and_then(|v| v.as_i64()),
                    daily_api.get("Remaining").and_then(|v| v.as_i64()),
                ) {
                    let usage_percent = ((max - remaining) as f64 / max as f64) * 100.0;
                    println!(
                        "  Daily API Usage: {:.1}% ({}/{})",
                        usage_percent,
                        max - remaining,
                        max
                    );

                    if usage_percent > 80.0 {
                        println!("  ⚠ Warning: API usage is above 80%!");
                    }
                }
            }
        }
        Err(e) => {
            println!("✗ Error retrieving limits: {}", e);
            println!("  Note: Check if rate limited or other error occurred");
        }
    }

    println!();
}

pub async fn versions(&self) -> Result<Vec<ApiVersion>, Error>

Get available API versions.

Trait Implementations

impl Clone for SalesforceRestClient

fn clone(&self) -> SalesforceRestClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SalesforceRestClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.