Update .gitignore, .Rbuildignore, and enhance error handling in fhir.R

- Added entries for `doc/` and `Meta/` to .gitignore and .Rbuildignore to exclude documentation and metadata files from version control.
- Introduced a new `error_to_string` function in fhir.R to improve error handling by converting various error formats into a consistent string representation for better debugging and user feedback.
- Updated example scripts to reflect changes in client initialization and error handling practices.

Author: alex-omophub

.Rbuildignore

@@ -10,3 +10,5 @@
 ^\.Rproj\.user$
 ^\.env$
 ^cran-comments\.md$
+^doc$
+^Meta$

.gitignore

@@ -37,4 +37,6 @@ codecov.yml
 .env
 .env.local
 .env.production
-cran-comments.md
+cran-comments.md
+/doc/
+/Meta/

R/fhir.R

@@ -201,6 +201,24 @@ fhir_batch_to_tibble <- function(result, codings) {
   items <- result$results %||% list()
   n <- length(codings)
 
+  # Collapse a possibly-nested error object to a scalar string. The API
+  # may return `error` as a plain string, a list like
+  # `list(code = "concept_not_found", message = "...")`, or something
+  # else. A list-column here would be expanded into extra tibble rows.
+  error_to_string <- function(err) {
+    if (is.null(err)) return(NA_character_)
+    if (is.character(err) && length(err) == 1L) return(err)
+    if (is.list(err)) {
+      msg <- err$message %||% err$code %||% err$detail
+      if (!is.null(msg) && is.character(msg) && length(msg) == 1L) {
+        return(msg)
+      }
+      return(paste(names(err) %||% "", unlist(lapply(err, as.character)),
+                   sep = "=", collapse = "; "))
+    }
+    as.character(err)[[1L]]
+  }
+
   make_row <- function(i) {
     input_coding <- codings[[i]]
     item <- if (i <= length(items)) items[[i]] else NULL
@@ -221,7 +239,7 @@ fhir_batch_to_tibble <- function(result, codings) {
         mapping_type = NA_character_,
         similarity_score = NA_real_,
         status = "failed",
-        status_detail = item$error %||% "unresolved"
+        status_detail = error_to_string(item$error)
       ))
     }
 

inst/examples/basic_usage.R

@@ -11,14 +11,18 @@
 
 library(omophub)
 
+# Null-coalescing operator (available in base R 4.4+; define locally for
+# compatibility with the R >= 4.1 package requirement).
+`%||%` <- function(a, b) if (is.null(a)) b else a
+
 # ============================================================================
 # Setup
 # ============================================================================
 
 # Initialize client (uses OMOPHUB_API_KEY environment variable)
 # You can also pass the API key directly:
-#   client <- omophub(api_key = "oh_your_api_key")
-client <- omophub()
+#   client <- OMOPHubClient$new(api_key = "oh_your_api_key")
+client <- OMOPHubClient$new()
 
 cat("OMOPHub R Client - Basic Usage Example\n")
 cat("======================================\n\n")