filemaker_lib/

lib.rs

#![doc = include_str!("../README.MD")]

use anyhow::{anyhow, Result};
use base64::Engine;
use log::*;
use percent_encoding::{utf8_percent_encode, NON_ALPHANUMERIC};
use reqwest::{Client, Method};
use serde::{Deserialize, Serialize};
use serde_json::{json, Value};
use std::collections::HashMap;
use std::sync::{Arc, RwLock};
use tokio::sync::Mutex;

static FM_URL: RwLock<Option<String>> = RwLock::new(None);

/// Represents a single record from a database query.
///
/// The generic type `T` represents the structure of the field data.
#[derive(Debug, Serialize, Deserialize, Default, Clone)]
pub struct Record<T> {
    /// The actual field data of the record, structured according to type T.
    #[serde(rename = "fieldData")]
    pub data: T,
    /// Related data from portal tables, stored as a generic JSON Value.
    #[serde(rename = "portalData")]
    pub portal_data: Value,
    /// Unique identifier for the record in the database.
    #[serde(rename = "recordId")]
    pub record_id: String,
    /// Modification identifier for the record, used for optimistic locking.
    #[serde(rename = "modId")]
    pub mod_id: String,
}

/// Container for the complete result of a find operation, including response data and messages.
///
/// The generic type `T` represents the structure of individual record data.
#[derive(Debug, Serialize, Deserialize, Default, Clone)]
pub struct FindResult<T> {
    /// The main response containing record data and metadata.
    pub response: Response<T>,
    /// List of messages returned by the database operation, often containing status or error information.
    pub messages: Vec<Message>,
}

/// Contains the response data from a find operation.
///
/// The generic type `T` represents the structure of individual record data.
#[derive(Debug, Serialize, Deserialize, Default, Clone)]
pub struct Response<T> {
    /// Metadata about the data returned from the find operation.
    #[serde(rename = "dataInfo")]
    pub info: DataInfo,
    /// Collection of records matching the find criteria.
    pub data: Vec<Record<T>>,
}

/// Represents a message returned by the database operations.
///
/// These messages typically provide information about the success or failure of operations.
#[derive(Debug, Serialize, Deserialize, Default, Clone)]
pub struct Message {
    /// The content of the message.
    pub message: String,
    /// A code associated with the message, often indicating the type of message or error.
    pub code: String,
}

/// Metadata about the data returned from a database query.
#[derive(Debug, Serialize, Deserialize, Default, Clone)]
pub struct DataInfo {
    /// Name of the database that was queried.
    pub database: String,
    /// Name of the layout used for the query.
    pub layout: String,
    /// Name of the table that was queried.
    pub table: String,
    /// Total number of records in the table before applying any filters.
    #[serde(rename = "totalRecordCount")]
    pub total_record_count: u64,
    /// Number of records that matched the find criteria.
    #[serde(rename = "foundCount")]
    pub found_count: u64,
    /// Number of records actually returned in the response (maybe limited by pagination).
    #[serde(rename = "returnedCount")]
    pub returned_count: u64,
}

/// Represents a connection to a Filemaker database with authentication and query capabilities.
///
/// This struct manages the connection details and authentication token needed
/// to interact with a Filemaker database through its Data API.
#[derive(Clone)]
pub struct Filemaker {
    // Name of the database to connect to
    database: String,
    // Authentication token stored in a thread-safe container that can be updated
    // Option is used since the token might not be available initially
    token: Arc<Mutex<Option<String>>>,
    // Name of the table/layout to operate on
    table: String,
    // HTTP client for making API requests
    client: Client,
}
impl Filemaker {
    /// Creates a new `Filemaker` instance.
    ///
    /// Initializes a connection to a FileMaker database with the provided credentials.
    /// This function performs authentication and sets up the HTTP client with appropriate configuration.
    ///
    /// # Arguments
    /// * `username` - The username for FileMaker authentication
    /// * `password` - The password for FileMaker authentication
    /// * `database` - The name of the FileMaker database to connect to
    /// * `table` - The name of the table/layout to operate on
    ///
    /// # Returns
    /// * `Result<Self>` - A new Filemaker instance or an error
    pub async fn new(username: &str, password: &str, database: &str, table: &str) -> Result<Self> {
        // URL-encode database and table names to handle spaces and special characters
        let encoded_database = utf8_percent_encode(database, NON_ALPHANUMERIC).to_string();
        let encoded_table = utf8_percent_encode(table, NON_ALPHANUMERIC).to_string();

        // Create an HTTP client that accepts invalid SSL certificates (for development)
        let client = Client::builder()
            .danger_accept_invalid_certs(true) // Disable SSL verification
            .build()
            .map_err(|e| {
                error!("Failed to build client: {}", e);
                anyhow::anyhow!(e)
            })?;

        // Authenticate with FileMaker and get a session token
        let token = Self::get_session_token(&client, database, username, password).await?;
        info!("Filemaker instance created successfully");

        // Return the initialized Filemaker instance
        Ok(Self {
            database: encoded_database,
            table: encoded_table,
            token: Arc::new(Mutex::new(Some(token))), // Wrap token in a thread-safe container
            client,
        })
    }

    /// Sets the `FM_URL` to the specified value.
    ///
    /// This function accepts a URL as an input parameter and updates the globally shared `FM_URL` variable.
    /// The provided `url` is converted to a `String` and stored in a thread-safe manner.
    ///
    /// # Parameters
    /// - `url`: A value that can be converted into a `String`. This is the new URL to set for `FM_URL`.
    ///
    /// # Returns
    /// - `Result<()>`: Returns `Ok(())` if the `FM_URL` was successfully updated. Returns an error
    ///   if there was a failure when trying to acquire a write lock or setting the value.
    ///
    /// # Errors
    /// This function will return an error if:
    /// - Acquiring a write lock on the `FM_URL` variable fails. This could happen if the lock is poisoned
    ///   or another thread panicked while holding the lock.
    ///
    /// # Examples
    /// ```rust
    /// set_fm_url("https://example.com")?;
    /// ```
    ///
    /// # Debug logs
    /// A debug log is emitted indicating the new URL being set.
    ///
    /// # Thread Safety
    /// This function uses a thread-safe write lock to ensure that changes to `FM_URL` are safe in
    /// a concurrent context.
    pub fn set_fm_url(url: impl Into<String>) -> Result<()> {
        let url = url.into();
        debug!("Setting FM_URL to {}", url);
        let mut writer = FM_URL
            .write()
            .map_err(|e| anyhow!("Failed to write to FM_URL: {}", e))?;
        *writer = Some(url);
        Ok(())
    }

    /// Retrieves the FM_URL configuration value.
    ///
    /// This function attempts to read the FM_URL value from a `RwLock`, ensuring
    /// thread-safety during the read process. If the lock cannot be obtained
    /// or the FM_URL is not set, the function will return an error.
    ///
    /// # Errors
    ///
    /// This function will return an error in the following cases:
    /// - If the `RwLock` cannot be read (e.g., poisoned due to a panic in another thread).
    /// - If the FM_URL value is not set (`None`).
    ///
    /// # Returns
    ///
    /// - `Ok(String)`: The FM_URL value as a `String` if it is successfully retrieved.
    /// - `Err(anyhow::Error)`: An error with context if reading the FM_URL fails or if it is not set.
    ///
    /// # Example
    ///
    /// ```rust
    /// match get_fm_url() {
    ///     Ok(url) => println!("FM_URL: {}", url),
    ///     Err(e) => eprintln!("Error retrieving FM_URL: {}", e),
    /// }
    /// ```
    fn get_fm_url() -> Result<String> {
        let rwlock = FM_URL
            .read()
            .map_err(|e| anyhow!("Failed to read FM_URL: {}", e))?;
        rwlock.clone().ok_or(anyhow!("FM_URL is not set"))
    }

    /// Gets a session token from the FileMaker Data API.
    ///
    /// Performs authentication against the FileMaker Data API and retrieves a session token
    /// that can be used for subsequent API requests.
    ///
    /// # Arguments
    /// * `client` - The HTTP client to use for the request
    /// * `database` - The name of the FileMaker database to authenticate against
    /// * `username` - The username for FileMaker authentication
    /// * `password` - The password for FileMaker authentication
    ///
    /// # Returns
    /// * `Result<String>` - The session token or an error
    async fn get_session_token(
        client: &Client,
        database: &str,
        username: &str,
        password: &str,
    ) -> Result<String> {
        // URL-encode the database name to handle spaces and special characters
        let database = utf8_percent_encode(database, NON_ALPHANUMERIC).to_string();

        // Construct the URL for the session endpoint
        let url = format!("{}/databases/{}/sessions", Self::get_fm_url()?, database);

        // Create a Base64-encoded Basic authentication header
        let auth_header = format!(
            "Basic {}",
            base64::engine::general_purpose::STANDARD.encode(format!("{}:{}", username, password))
        );

        debug!("Requesting session token from URL: {}", url);

        // Send the authentication request to FileMaker
        let response = client
            .post(&url)
            .header("Authorization", auth_header)
            .header("Content-Type", "application/json")
            .body("{}") // Empty JSON body for session creation
            .send()
            .await
            .map_err(|e| {
                error!("Failed to send request for session token: {}", e);
                anyhow::anyhow!(e)
            })?;

        // Parse the JSON response
        let json: Value = response.json().await.map_err(|e| {
            error!("Failed to parse session token response: {}", e);
            anyhow::anyhow!(e)
        })?;

        // Extract the token from the response JSON structure
        if let Some(token) = json
            .get("response")
            .and_then(|r| r.get("token"))
            .and_then(|t| t.as_str())
        {
            info!("Session token retrieved successfully");
            Ok(token.to_string())
        } else {
            error!(
                "Failed to get token from FileMaker API response: {:?}",
                json
            );
            Err(anyhow::anyhow!("Failed to get token from FileMaker API"))
        }
    }

    /// Sends an authenticated HTTP request to the FileMaker Data API.
    ///
    /// This method handles adding the authentication token to requests and processing
    /// the response from the FileMaker Data API.
    ///
    /// # Arguments
    /// * `url` - The endpoint URL to send the request to
    /// * `method` - The HTTP method to use (GET, POST, etc.)
    /// * `body` - Optional JSON body to include with the request
    ///
    /// # Returns
    /// * `Result<Value>` - The parsed JSON response or an error
    async fn authenticated_request(
        &self,
        url: &str,
        method: Method,
        body: Option<Value>,
    ) -> Result<Value> {
        // Retrieve the session token from the shared state
        let token = self.token.lock().await.clone();
        if token.is_none() {
            error!("No session token found");
            return Err(anyhow::anyhow!("No session token found"));
        }

        // Create Bearer authentication header with the token
        let auth_header = format!("Bearer {}", token.unwrap());

        // Start building the request with appropriate headers
        let mut request = self
            .client
            .request(method, url)
            .header("Authorization", auth_header)
            .header("Content-Type", "application/json");

        // Add the JSON body to the request if provided
        if let Some(body_content) = body {
            let json_body = serde_json::to_string(&body_content).map_err(|e| {
                error!("Failed to serialize request body: {}", e);
                anyhow::anyhow!(e)
            })?;
            debug!("Request body: {}", json_body);
            request = request.body(json_body);
        }

        debug!("Sending authenticated request to URL: {}", url);

        // Send the request and handle any network errors
        let response = request.send().await.map_err(|e| {
            error!("Failed to send authenticated request: {}", e);
            anyhow::anyhow!(e)
        })?;

        // Parse the response JSON and handle parsing errors
        let json: Value = response.json().await.map_err(|e| {
            error!("Failed to parse authenticated request response: {}", e);
            anyhow::anyhow!(e)
        })?;

        info!("Authenticated request to {} completed successfully", url);
        Ok(json)
    }

    /// Retrieves a specified range of records from the database.
    ///
    /// # Arguments
    /// * `start` - The starting position (offset) for record retrieval
    /// * `limit` - The maximum number of records to retrieve
    ///
    /// # Returns
    /// * `Result<Vec<Value>>` - A vector of record objects on success, or an error
    pub async fn get_records<T>(&self, start: T, limit: T) -> Result<Vec<Value>>
    where
        T: Sized + Clone + std::fmt::Display + std::str::FromStr + TryFrom<usize>,
    {
        // Construct the URL for the FileMaker Data API records endpoint
        let url = format!(
            "{}/databases/{}/layouts/{}/records?_offset={}&_limit={}",
            Self::get_fm_url()?,
            self.database,
            self.table,
            start,
            limit
        );
        debug!("Fetching records from URL: {}", url);

        // Send authenticated request to the API endpoint
        let response = self.authenticated_request(&url, Method::GET, None).await?;

        // Extract the records data from the response if available
        if let Some(data) = response.get("response").and_then(|r| r.get("data")) {
            info!("Successfully retrieved records from database");
            Ok(data.as_array().unwrap_or(&vec![]).clone())
        } else {
            // Log and return error if the expected data structure is not found
            error!("Failed to retrieve records from response: {:?}", response);
            Err(anyhow::anyhow!("Failed to retrieve records"))
        }
    }

    /// Retrieves all records from the database in a single query.
    ///
    /// This method first determines the total record count and then
    /// fetches all records in a single request.
    ///
    /// # Returns
    /// * `Result<Vec<Value>>` - A vector containing all records on success, or an error
    pub async fn get_all_records_raw(&self) -> Result<Vec<Value>> {
        // First get the total number of records in the database
        let total_count = self.get_number_of_records().await?;
        debug!("Total records to fetch: {}", total_count);

        // Retrieve all records in a single request
        self.get_records(1, total_count).await
    }

    /// Asynchronously retrieves all records from the data source, deserializing them into the specified type.
    ///
    /// # Type Parameters
    /// - `T`: The type into which each record will be deserialized. It must implement the
    ///   `serde::de::DeserializeOwned` trait.
    ///
    /// # Returns
    /// - `Ok(Vec<T>)`: A vector of deserialized records of type `T` if the operation is successful.
    /// - `Err(anyhow::Error)`: An error if there is an issue with retrieving raw records, missing
    ///   `fieldData`, or deserialization failure.
    ///
    /// # Errors
    /// - Returns an error if:
    ///   - The `get_all_records_raw` method fails to retrieve data.
    ///   - A record is missing the `fieldData` field, which is required for deserialization.
    ///   - Deserialization of the `fieldData` into type `T` fails. The error logs the specific reason for failure
    ///     and the problematic data.
    ///
    /// # Logs
    /// - Logs an error if:
    ///   - Deserialization of a record fails, indicating the cause and the corresponding `fieldData`.
    ///   - A record lacks the required `fieldData`, with the full problematic record logged.
    ///
    /// # Examples
    ///
    /// ```rust
    /// #[derive(serde::Deserialize)]
    /// struct MyRecord {
    ///     id: u32,
    ///     name: String,
    /// }
    ///
    /// let data_source = MyDataSource::new();
    /// let records: Vec<MyRecord> = data_source.get_all_records().await.unwrap();
    /// for record in records {
    ///     println!("Record ID: {}, Name: {}", record.id, record.name);
    /// }
    /// ```
    ///
    /// Make sure that the deserialization type `T` matches the structure of the data being retrieved from the source.
    pub async fn get_all_records<T>(&self) -> Result<Vec<T>>
    where
        T: serde::de::DeserializeOwned,
    {
        let raw = self.get_all_records_raw().await?;
        let mut items: Vec<T> = vec![];
        for item in raw {
            if let Some(data) = item.get("fieldData") {
                let deserialized: T = serde_json::from_value(data.clone()).map_err(|e| {
                    error!("Failed to deserialize record: {}. Response: {:?}", e, data);
                    anyhow::anyhow!(e)
                })?;
                items.push(deserialized);
            } else {
                error!(
                    "Failed to deserialize record, fieldData is missing: {:?}",
                    item
                );
                return Err(anyhow::anyhow!(
                    "Failed to deserialize record, fieldData is missing"
                ));
            }
        }

        Ok(items)
    }

    /// Retrieves the total number of records in the database table.
    ///
    /// # Returns
    /// * `Result<u64>` - The total record count on success, or an error
    pub async fn get_number_of_records(&self) -> Result<u64> {
        // Construct the URL for the FileMaker Data API records endpoint
        let url = format!(
            "{}/databases/{}/layouts/{}/records",
            Self::get_fm_url()?,
            self.database,
            self.table
        );
        debug!("Fetching total number of records from URL: {}", url);

        // Send authenticated request to the API endpoint
        let response = self.authenticated_request(&url, Method::GET, None).await?;

        // Extract the total record count from the response if available
        if let Some(total_count) = response
            .get("response")
            .and_then(|r| r.get("dataInfo"))
            .and_then(|d| d.get("totalRecordCount"))
            .and_then(|c| c.as_u64())
        {
            info!("Total record count retrieved successfully: {}", total_count);
            Ok(total_count)
        } else {
            // Log and return error if the expected data structure is not found
            error!(
                "Failed to retrieve total record count from response: {:?}",
                response
            );
            Err(anyhow::anyhow!("Failed to retrieve total record count"))
        }
    }

    /// Searches the database for records matching specified criteria.
    ///
    /// # Arguments
    /// * `query` - Vector of field-value pairs to search for
    /// * `sort` - Vector of field names to sort by
    /// * `ascending` - Whether to sort in ascending (true) or descending (false) order
    /// * `limit` - If None, all results will be returned; otherwise, the specified limit will be applied
    ///
    /// # Returns
    /// * `Result<Vec<T>>` - A vector of matching records as the specified type on success, or an error
    pub async fn search<T>(
        &self,
        query: Vec<HashMap<String, String>>,
        sort: Vec<String>,
        ascending: bool,
        limit: Option<u64>,
    ) -> Result<FindResult<T>>
    where
        T: serde::de::DeserializeOwned + Default,
    {
        // Construct the URL for the FileMaker Data API find endpoint
        let url = format!(
            "{}/databases/{}/layouts/{}/_find",
            Self::get_fm_url()?,
            self.database,
            self.table
        );

        // Determine sort order based on ascending parameter
        let sort_order = if ascending { "ascend" } else { "descend" };

        // Transform the sort fields into the format expected by FileMaker API
        let sort_map: Vec<_> = sort
            .into_iter()
            .map(|s| {
                let mut map = HashMap::new();
                map.insert("fieldName".to_string(), s);
                map.insert("sortOrder".to_string(), sort_order.to_string());
                map
            })
            .collect();

        // Construct the request body with query and sort parameters
        let mut body: HashMap<String, Value> = HashMap::from([
            ("query".to_string(), serde_json::to_value(query)?),
            ("sort".to_string(), serde_json::to_value(sort_map)?),
        ]);
        if let Some(limit) = limit {
            body.insert("limit".to_string(), serde_json::to_value(limit)?);
        } else {
            body.insert("limit".to_string(), serde_json::to_value(u32::MAX)?);
        }
        debug!("Executing search query with URL: {}. Body: {:?}", url, body);

        // Send authenticated POST request to the API endpoint
        let response = self
            .authenticated_request(&url, Method::POST, Some(serde_json::to_value(body)?))
            .await?;

        // Extract the search results and deserialize into the specified type
        let deserialized: FindResult<T> =
            serde_json::from_value(response.clone()).map_err(|e| {
                error!(
                    "Failed to deserialize search results: {}. Response: {:?}",
                    e, response
                );
                anyhow::anyhow!(e)
            })?;
        info!("Search query executed successfully");
        Ok(deserialized)
    }

    /// Adds a record to the database.
    ///
    /// # Parameters
    /// - `field_data`: A `HashMap` representing the field data for the new record.
    ///
    /// # Returns
    /// A `Result` containing the added record as a `Value` on success, or an error.
    pub async fn add_record(
        &self,
        field_data: HashMap<String, Value>,
    ) -> Result<HashMap<String, Value>> {
        // Define the URL for the FileMaker Data API endpoint
        let url = format!(
            "{}/databases/{}/layouts/{}/records",
            Self::get_fm_url()?,
            self.database,
            self.table
        );

        // Prepare the request body
        let field_data_map: serde_json::Map<String, Value> = field_data.into_iter().collect();
        let body = HashMap::from([("fieldData".to_string(), Value::Object(field_data_map))]);

        debug!("Adding a new record. URL: {}. Body: {:?}", url, body);

        // Make the API call
        let response = self
            .authenticated_request(&url, Method::POST, Some(serde_json::to_value(body)?))
            .await?;

        if let Some(record_id) = response
            .get("response")
            .and_then(|r| r.get("recordId"))
            .and_then(|id| id.as_str())
        {
            if let Ok(record_id) = record_id.parse::<u64>() {
                debug!("Record added successfully. Record ID: {}", record_id);
                let added_record = self.get_record_by_id(record_id).await?;
                Ok(HashMap::from([
                    ("success".to_string(), Value::Bool(true)),
                    ("result".to_string(), added_record),
                ]))
            } else {
                error!("Failed to parse record id {} - {:?}", record_id, response);
                Ok(HashMap::from([
                    ("success".to_string(), Value::Bool(false)),
                    ("result".to_string(), response),
                ]))
            }
        } else {
            error!("Failed to add the record: {:?}", response);
            Ok(HashMap::from([
                ("success".to_string(), Value::Bool(false)),
                ("result".to_string(), response),
            ]))
        }
    }

    /// Updates a record in the database using the FileMaker Data API.
    ///
    /// # Arguments
    /// * `id` - The unique identifier of the record to update
    /// * `field_data` - A hashmap containing the field names and their new values
    ///
    /// # Returns
    /// * `Result<Value>` - The server response as a JSON value or an error
    ///
    /// # Type Parameters
    /// * `T` - A type that can be used as a record identifier and meets various trait requirements
    pub async fn update_record<T>(&self, id: T, field_data: HashMap<String, Value>) -> Result<Value>
    where
        T: Sized + Clone + std::fmt::Display + std::str::FromStr + TryFrom<usize>,
    {
        // Construct the API endpoint URL for updating a specific record
        let url = format!(
            "{}/databases/{}/layouts/{}/records/{}",
            Self::get_fm_url()?,
            self.database,
            self.table,
            id
        );

        // Convert the field data hashmap to the format expected by FileMaker Data API
        let field_data_map: serde_json::Map<String, Value> = field_data.into_iter().collect();
        // Create the request body with fieldData property
        let body = HashMap::from([("fieldData".to_string(), Value::Object(field_data_map))]);

        debug!("Updating record ID: {}. URL: {}. Body: {:?}", id, url, body);

        // Send the PATCH request to update the record
        let response = self
            .authenticated_request(&url, Method::PATCH, Some(serde_json::to_value(body)?))
            .await?;

        info!("Record ID: {} updated successfully", id);
        Ok(response)
    }

    /// Retrieves the list of databases accessible to the specified user.
    ///
    /// # Arguments
    /// * `username` - The FileMaker username for authentication
    /// * `password` - The FileMaker password for authentication
    ///
    /// # Returns
    /// * `Result<Vec<String>>` - A list of accessible database names or an error
    pub async fn get_databases(username: &str, password: &str) -> Result<Vec<String>> {
        // Construct the API endpoint URL for retrieving databases
        let url = format!("{}/databases", Self::get_fm_url()?);

        // Create Base64 encoded Basic auth header from username and password
        let auth_header = format!(
            "Basic {}",
            base64::engine::general_purpose::STANDARD.encode(format!("{}:{}", username, password))
        );

        debug!("Fetching list of databases from URL: {}", url);

        // Initialize HTTP client
        let client = Client::new();

        // Send request to get list of databases with authentication
        let response = client
            .get(&url)
            .header("Authorization", auth_header)
            .header("Content-Type", "application/json")
            .send()
            .await
            .map_err(|e| {
                error!("Failed to send request for databases: {}", e);
                anyhow::anyhow!(e)
            })?
            .json::<Value>()
            .await
            .map_err(|e| {
                error!("Failed to parse database list response: {}", e);
                anyhow::anyhow!(e)
            })?;

        // Extract database names from the response JSON
        if let Some(databases) = response
            .get("response")
            .and_then(|r| r.get("databases"))
            .and_then(|d| d.as_array())
        {
            // Extract the name field from each database object
            let database_names = databases
                .iter()
                .filter_map(|db| {
                    db.get("name")
                        .and_then(|n| n.as_str())
                        .map(|s| s.to_string())
                })
                .collect();

            info!("Database list retrieved successfully");
            Ok(database_names)
        } else {
            // Handle case where response doesn't contain expected data structure
            error!("Failed to retrieve databases from response: {:?}", response);
            Err(anyhow::anyhow!("Failed to retrieve databases"))
        }
    }

    /// Retrieves the list of layouts for the specified database using the provided credentials.
    ///
    /// # Arguments
    /// * `username` - The FileMaker username for authentication
    /// * `password` - The FileMaker password for authentication
    /// * `database` - The name of the database to get layouts from
    ///
    /// # Returns
    /// * `Result<Vec<String>>` - A list of layout names or an error
    pub async fn get_layouts(
        username: &str,
        password: &str,
        database: &str,
    ) -> Result<Vec<String>> {
        // URL encode the database name and construct the API endpoint URL
        let encoded_database = utf8_percent_encode(database, NON_ALPHANUMERIC).to_string();
        let url = format!(
            "{}/databases/{}/layouts",
            Self::get_fm_url()?,
            encoded_database
        );

        debug!("Fetching layouts from URL: {}", url);

        // Create HTTP client and get session token for authentication
        let client = Client::new();
        let token = Self::get_session_token(&client, database, username, password)
            .await
            .map_err(|e| {
                error!("Failed to get session token for layouts: {}", e);
                anyhow::anyhow!(e)
            })?;

        // Create Bearer auth header from the session token
        let auth_header = format!("Bearer {}", token);

        // Send request to get list of layouts with token authentication
        let response = client
            .get(&url)
            .header("Authorization", auth_header)
            .header("Content-Type", "application/json")
            .send()
            .await
            .map_err(|e| {
                error!("Failed to send request to retrieve layouts: {}", e);
                anyhow::anyhow!(e)
            })?
            .json::<Value>()
            .await
            .map_err(|e| {
                error!("Failed to parse response for layouts: {}", e);
                anyhow::anyhow!(e)
            })?;

        // Extract layout names from the response JSON
        if let Some(layouts) = response
            .get("response")
            .and_then(|r| r.get("layouts"))
            .and_then(|l| l.as_array())
        {
            // Extract the name field from each layout object
            let layout_names = layouts
                .iter()
                .filter_map(|layout| {
                    layout
                        .get("name")
                        .and_then(|n| n.as_str())
                        .map(|s| s.to_string())
                })
                .collect();

            info!("Successfully retrieved layouts");
            Ok(layout_names)
        } else {
            // Handle case where response doesn't contain expected data structure
            error!("Failed to retrieve layouts from response: {:?}", response);
            Err(anyhow::anyhow!("Failed to retrieve layouts"))
        }
    }

    /// Gets a record from the database by its ID.
    ///
    /// # Arguments
    /// * `id` - The ID of the record to get.
    ///
    /// # Returns
    /// A JSON object representing the record.
    pub async fn get_record_by_id<T>(&self, id: T) -> Result<Value>
    where
        T: Sized + Clone + std::fmt::Display + std::str::FromStr + TryFrom<usize>,
    {
        let url = format!(
            "{}/databases/{}/layouts/{}/records/{}",
            Self::get_fm_url()?,
            self.database,
            self.table,
            id
        );

        debug!("Fetching record with ID: {} from URL: {}", id, url);

        let response = self
            .authenticated_request(&url, Method::GET, None)
            .await
            .map_err(|e| {
                error!("Failed to get record ID {}: {}", id, e);
                anyhow::anyhow!(e)
            })?;

        if let Some(data) = response.get("response").and_then(|r| r.get("data")) {
            if let Some(record) = data.as_array().and_then(|arr| arr.first()) {
                info!("Record ID {} retrieved successfully", id);
                Ok(record.clone())
            } else {
                error!("No record found for ID {}", id);
                Err(anyhow::anyhow!("No record found"))
            }
        } else {
            error!("Failed to get record from response: {:?}", response);
            Err(anyhow::anyhow!("Failed to get record"))
        }
    }

    /// Deletes a record from the database by its ID.
    ///
    /// # Arguments
    /// * `id` - The ID of the record to delete.
    ///
    /// # Returns
    /// A result indicating the deletion was successful or an error message.
    pub async fn delete_record<T>(&self, id: T) -> Result<Value>
    where
        T: Sized + Clone + std::fmt::Display + std::str::FromStr + TryFrom<usize>,
    {
        let url = format!(
            "{}/databases/{}/layouts/{}/records/{}",
            Self::get_fm_url()?,
            self.database,
            self.table,
            id
        );

        debug!("Deleting record with ID: {} at URL: {}", id, url);

        let response = self
            .authenticated_request(&url, Method::DELETE, None)
            .await
            .map_err(|e| {
                error!("Failed to delete record ID {}: {}", id, e);
                anyhow::anyhow!(e)
            })?;

        if response.is_object() {
            info!("Record ID {} deleted successfully", id);
            Ok(json!({"success": true}))
        } else {
            error!("Failed to delete record ID {}", id);
            Err(anyhow::anyhow!("Failed to delete record"))
        }
    }

    /// Deletes the specified database.
    ///
    /// # Arguments
    /// * `database` - The name of the database to delete.
    /// * `username` - The username for authentication.
    /// * `password` - The password for authentication.
    pub async fn delete_database(database: &str, username: &str, password: &str) -> Result<()> {
        let encoded_database = utf8_percent_encode(database, NON_ALPHANUMERIC).to_string();
        let url = format!("{}/databases/{}", Self::get_fm_url()?, encoded_database);

        debug!("Deleting database: {}", database);

        let client = Client::new();
        let token = Self::get_session_token(&client, database, username, password)
            .await
            .map_err(|e| {
                error!("Failed to get session token for database deletion: {}", e);
                anyhow::anyhow!(e)
            })?;
        let auth_header = format!("Bearer {}", token);

        client
            .delete(&url)
            .header("Authorization", auth_header)
            .header("Content-Type", "application/json")
            .send()
            .await
            .map_err(|e| {
                error!("Failed to delete database {}: {}", database, e);
                anyhow::anyhow!(e)
            })?;

        info!("Database {} deleted successfully", database);
        Ok(())
    }

    /// Deletes all records from the current database.
    ///
    /// This function retrieves and systematically removes all records from the database.
    /// It first checks if there are any records to delete, then proceeds with deletion
    /// if records exist.
    ///
    /// # Returns
    /// * `Result<()>` - Ok(()) if all records were successfully deleted, or an error
    ///
    /// # Errors
    /// * Returns error if unable to retrieve records
    /// * Returns error if record ID parsing fails
    /// * Returns error if record deletion fails
    pub async fn clear_database(&self) -> Result<()> {
        debug!("Clearing all records from the database");
        // Get the total count of records in the database
        let number_of_records = self.get_number_of_records().await?;

        // Check if there are any records to delete
        if number_of_records == 0 {
            warn!("No records found in the database. Nothing to clear");
            return Ok(());
        }

        // Retrieve all records that need to be deleted
        // The number_of_records value is used as limit to fetch all records at once
        let records = self.get_records(1, number_of_records).await.map_err(|e| {
            error!("Failed to retrieve records for clearing database: {}", e);
            anyhow::anyhow!(e)
        })?;

        // Iterate through each record and delete it individually
        for record in records {
            // Extract the record ID from the record data
            if let Some(id) = record.get("recordId").and_then(|id| id.as_str()) {
                // The record ID is usually marked as a string even though it's a u64,
                // so we need to parse it to the correct type
                if let Ok(id) = id.parse::<u64>() {
                    debug!("Deleting record ID: {}", id);
                    // Attempt to delete the record and handle any errors
                    if let Err(e) = self.delete_record(id).await {
                        error!("Failed to delete record ID {}: {}", id, e);
                        return Err(anyhow::anyhow!(e));
                    }
                } else {
                    // Handle case where ID exists but cannot be parsed as u64
                    error!("Failed to parse record ID {} as u64", id);
                    return Err(anyhow::anyhow!("Failed to parse record ID as u64"));
                }
            } else {
                // Handle case where record doesn't contain an ID field
                error!("Record ID not found in record: {:?}", record);
                return Err(anyhow::anyhow!(
                    "Record ID not found in record: {:?}",
                    record
                ));
            }
        }

        info!("All records cleared from the database");
        Ok(())
    }
    /// Returns the names of fields in the given record excluding the ones starting with 'g_' (global fields)
    ///
    /// # Arguments
    /// * `record` - An example record with 'fieldData' element containing field names as keys.
    ///
    /// # Returns
    /// An array of field names.
    pub fn get_row_names_by_example(record: &Value) -> Vec<String> {
        let mut fields = Vec::new();
        if let Some(field_data) = record.get("fieldData").and_then(|fd| fd.as_object()) {
            for field in field_data.keys() {
                if !field.starts_with("g_") {
                    fields.push(field.clone());
                }
            }
        }
        info!("Extracted row names: {:?}", fields);
        fields
    }

    /// Gets the field names for the first record in the database.
    ///
    /// This function retrieves a single record from the database and extracts
    /// field names from it. If no records exist, an empty vector is returned.
    ///
    /// # Returns
    /// * `Result<Vec<String>>` - A vector of field names on success, or an error
    pub async fn get_row_names(&self) -> Result<Vec<String>> {
        debug!("Attempting to fetch field names for the first record");

        // Fetch just the first record to use as a template
        let records = self.get_records(1, 1).await?;

        if let Some(first_record) = records.first() {
            info!("Successfully fetched field names for the first record");
            // Extract field names from the first record using the helper method
            return Ok(Self::get_row_names_by_example(first_record));
        }

        // Handle the case where no records exist in the database
        warn!("No records found while fetching field names");
        Ok(vec![])
    }

    /// Searches the database for records matching the specified query.
    ///
    /// # Arguments
    /// * `fields` - The query fields.
    /// * `sort` - The sort order.
    /// * `ascending` - Whether to sort in ascending order.
    ///
    /// # Returns
    /// A vector of matching records.
    pub async fn advanced_search(
        &self,
        fields: HashMap<String, Value>,
        sort: Vec<String>,
        ascending: bool,
    ) -> Result<Vec<Value>> {
        let url = format!(
            "{}/databases/{}/layouts/{}/_find",
            Self::get_fm_url()?,
            self.database,
            self.table
        );

        debug!(
            "Preparing advanced search with fields: {:?}, sort: {:?}, ascending: {}",
            fields, sort, ascending
        );

        let mut content = serde_json::Map::new();
        content.insert(
            "query".to_string(),
            Value::Array(fields.into_iter().map(|(k, v)| json!({ k: v })).collect()),
        );

        if !sort.is_empty() {
            let sort_array: Vec<Value> = sort
                .into_iter()
                .map(|s| {
                    json!({
                        "fieldName": s,
                        "sortOrder": if ascending { "ascend" } else { "descend" }
                    })
                })
                .collect();
            content.insert("sort".to_string(), Value::Array(sort_array));
        }

        debug!(
            "Sending authenticated request to URL: {} with content: {:?}",
            url, content
        );

        let response = self
            .authenticated_request(&url, Method::POST, Some(Value::Object(content)))
            .await?;

        if let Some(data) = response
            .get("response")
            .and_then(|r| r.get("data"))
            .and_then(|d| d.as_array())
        {
            info!(
                "Advanced search completed successfully, retrieved {} records",
                data.len()
            );
            Ok(data.clone())
        } else {
            error!("Failed to retrieve advanced search results: {:?}", response);
            Err(anyhow::anyhow!(
                "Failed to retrieve advanced search results"
            ))
        }
    }
}