Enhance documentation, add new dependencies, and improve data parsing logic

- Update .Rbuildignore to exclude additional files
- Add 'withr' to DESCRIPTION suggests
- Improve documentation for ORCID API functions, including expanded-search endpoint
- Refactor data parsing functions to handle edge cases and avoid duplicates
- Add WORDLIST for common terms used in the package
- Include 'withr' library in test setup

Author: lorenzoFabbri

.Rbuildignore

@@ -14,3 +14,7 @@
 ^altdoc$
 ^doc$
 ^Meta$
+^coverage\.html$
+^DEVELOPMENT\.md$
+^lib$
+^TODO\.md$

DESCRIPTION

@@ -21,6 +21,7 @@ Imports:
     jsonlite (>= 1.8.0)
 Suggests: 
     testthat (>= 3.0.0),
+    withr,
     knitr,
     rmarkdown
 Config/testthat/edition: 3

R/api-works.R

@@ -16,7 +16,10 @@
 #'     \item{orcid}{ORCID identifier}
 #'     \item{put_code}{Unique identifier for this work record}
 #'     \item{title}{Title of the work}
-#'     \item{type}{Type of work (e.g., journal-article, dataset, preprint)}
+#'     \item{type}{Type of work. Common values include: "journal-article",
+#'       "conference-paper", "conference-poster", "book", "book-chapter",
+#'       "dissertation", "data-set", "preprint", "report", "working-paper",
+#'       "other". Use this field to distinguish between different publication types.}
 #'     \item{publication_date}{Publication date (ISO format)}
 #'     \item{journal}{Journal or venue name (if available)}
 #'     \item{doi}{Digital Object Identifier (if available)}
@@ -47,9 +50,11 @@
 #' works <- orcid_works("0000-0002-1825-0097")
 #' print(works)
 #'
-#' # Filter by type
-#' articles <- works[type == "journal-article"]
+#' # Filter by type to distinguish between different publication types
+#' journal_articles <- works[type == "journal-article"]
+#' conference_posters <- works[type == "conference-poster"]
 #' datasets <- works[type == "data-set"]
+#' preprints <- works[type == "preprint"]
 #'
 #' # With authentication
 #' Sys.setenv(ORCID_TOKEN = "your-token-here")

R/parsers.R

@@ -133,54 +133,55 @@ parse_works <- function(json_data, orcid_id) {
 
   records <- lapply(groups, function(group) {
     summaries <- safe_extract(group, "work-summary")
-    if (is.null(summaries)) {
+    if (is.null(summaries) || length(summaries) == 0) {
       return(NULL)
     }
 
-    lapply(summaries, function(summary) {
-      if (is.null(summary)) {
-        return(NULL)
-      }
+    # Only take the first work-summary to avoid duplicates
+    # Multiple work-summaries in a group represent the same work from different sources
+    summary <- summaries[[1]]
 
-      # Extract title
-      title <- safe_extract(summary, "title", "title", "value")
-
-      # Extract DOI from external IDs
-      doi <- NA_character_
-      ext_ids <- safe_extract(summary, "external-ids", "external-id")
-      if (!is.null(ext_ids) && is.list(ext_ids)) {
-        for (ext_id in ext_ids) {
-          if (
-            !is.null(ext_id) &&
-              identical(safe_extract(ext_id, "external-id-type"), "doi")
-          ) {
-            doi <- safe_extract(ext_id, "external-id-value")
-            break
-          }
+    if (is.null(summary)) {
+      return(NULL)
+    }
+
+    # Extract title
+    title <- safe_extract(summary, "title", "title", "value")
+
+    # Extract DOI from external IDs
+    doi <- NA_character_
+    ext_ids <- safe_extract(summary, "external-ids", "external-id")
+    if (!is.null(ext_ids) && is.list(ext_ids)) {
+      for (ext_id in ext_ids) {
+        if (
+          !is.null(ext_id) &&
+            identical(safe_extract(ext_id, "external-id-type"), "doi")
+        ) {
+          doi <- safe_extract(ext_id, "external-id-value")
+          break
         }
       }
+    }
 
-      # Extract URL
-      url <- safe_extract(summary, "url", "value")
+    # Extract URL
+    url <- safe_extract(summary, "url", "value")
 
-      list(
-        orcid = orcid_id,
-        put_code = as.character(safe_extract(summary, "put-code")),
-        title = title,
-        type = safe_extract(summary, "type"),
-        publication_date = orcid_date_to_iso(safe_extract(
-          summary,
-          "publication-date"
-        )),
-        journal = safe_extract(summary, "journal-title", "value"),
-        doi = doi,
-        url = url
-      )
-    })
+    list(
+      orcid = orcid_id,
+      put_code = as.character(safe_extract(summary, "put-code")),
+      title = title,
+      type = safe_extract(summary, "type"),
+      publication_date = orcid_date_to_iso(safe_extract(
+        summary,
+        "publication-date"
+      )),
+      journal = safe_extract(summary, "journal-title", "value"),
+      doi = doi,
+      url = url
+    )
   })
 
-  records_flat <- unlist(records, recursive = FALSE)
-  records_flat <- records_flat[!vapply(records_flat, is.null, logical(1))]
+  records_flat <- records[!vapply(records, is.null, logical(1))]
 
   if (length(records_flat) == 0) {
     return(data.table::data.table(
@@ -364,7 +365,12 @@ parse_peer_reviews <- function(json_data, orcid_id) {
 parse_affiliations <- function(json_data, orcid_id) {
   groups <- safe_extract(json_data, "affiliation-group")
 
-  if (is.null(groups) || length(groups) == 0) {
+  # Check if groups is NA (not just NULL)
+  if (
+    is.null(groups) ||
+      length(groups) == 0 ||
+      (length(groups) == 1 && is.na(groups))
+  ) {
     return(data.table::data.table(
       orcid = character(0),
       put_code = character(0),
@@ -381,26 +387,26 @@ parse_affiliations <- function(json_data, orcid_id) {
 
   records <- lapply(groups, function(group) {
     summaries <- safe_extract(group, "summaries")
-    if (is.null(summaries)) {
+    if (is.null(summaries) || (length(summaries) == 1 && is.na(summaries))) {
       return(NULL)
     }
 
     lapply(summaries, function(item) {
       # Try different summary types
       summary <- safe_extract(item, "distinction-summary")
-      if (is.null(summary)) {
+      if (is.null(summary) || (length(summary) == 1 && is.na(summary))) {
         summary <- safe_extract(item, "invited-position-summary")
       }
-      if (is.null(summary)) {
+      if (is.null(summary) || (length(summary) == 1 && is.na(summary))) {
         summary <- safe_extract(item, "membership-summary")
       }
-      if (is.null(summary)) {
+      if (is.null(summary) || (length(summary) == 1 && is.na(summary))) {
         summary <- safe_extract(item, "qualification-summary")
       }
-      if (is.null(summary)) {
+      if (is.null(summary) || (length(summary) == 1 && is.na(summary))) {
         summary <- safe_extract(item, "service-summary")
       }
-      if (is.null(summary)) {
+      if (is.null(summary) || (length(summary) == 1 && is.na(summary))) {
         return(NULL)
       }
 
@@ -932,8 +938,13 @@ parse_search_results <- function(json_data) {
     num_found <- 0L
   }
 
-  # Extract results array
-  results <- safe_extract(json_data, "result")
+  # Extract results array - use expanded-result for v3.0 API
+  results <- safe_extract(json_data, "expanded-result")
+
+  # Fall back to "result" if expanded-result doesn't exist (older API versions)
+  if (is.null(results) || (length(results) == 1 && is.na(results))) {
+    results <- safe_extract(json_data, "result")
+  }
 
   # Handle empty results (safe_extract returns NA for null)
   if (
@@ -954,36 +965,55 @@ parse_search_results <- function(json_data) {
 
   # Parse each result
   parsed <- lapply(results, function(item) {
-    # Extract ORCID identifier
+    # Extract ORCID identifier - handle both formats
     orcid_path <- safe_extract(item, "orcid-identifier", "path")
-    orcid_id <- if (!is.null(orcid_path)) orcid_path else NA_character_
-
-    # Extract given names
-    given_names <- safe_extract(item, "given-names")
-    if (is.null(given_names)) {
-      given_names <- NA_character_
+    if (is.null(orcid_path) || is.na(orcid_path)) {
+      # Try direct orcid-id field (expanded-search format)
+      orcid_path <- item[["orcid-id"]]
     }
-
-    # Extract family name
-    family_name <- safe_extract(item, "family-names")
-    if (is.null(family_name)) {
-      family_name <- NA_character_
-    }
-
-    # Extract credit name
-    credit_names <- safe_extract(item, "credit-name")
-    credit_name <- if (!is.null(credit_names) && length(credit_names) > 0) {
-      credit_names[[1]]
+    orcid_id <- if (!is.null(orcid_path) && !is.na(orcid_path)) {
+      orcid_path
     } else {
       NA_character_
     }
 
+    # Helper function to safely extract and convert to character
+    extract_name_field <- function(field_name) {
+      val <- item[[field_name]]
+      if (is.null(val)) {
+        return(NA_character_)
+      }
+      if (length(val) == 0) {
+        return(NA_character_)
+      }
+      if (is.list(val)) {
+        # If it's a list, try to get the first non-null element
+        for (i in seq_along(val)) {
+          if (!is.null(val[[i]]) && length(val[[i]]) > 0) {
+            return(as.character(val[[i]]))
+          }
+        }
+        return(NA_character_)
+      }
+      # Direct value
+      return(as.character(val))
+    }
+
+    # Extract name fields
+    given_names <- extract_name_field("given-names")
+    family_name <- extract_name_field("family-names")
+    credit_name <- extract_name_field("credit-name")
+
     # Extract other names
-    other_names_data <- safe_extract(item, "other-names")
+    other_names_val <- item[["other-names"]]
+    if (is.null(other_names_val)) {
+      # Try alternate field name
+      other_names_val <- item[["other-name"]]
+    }
     other_names <- if (
-      !is.null(other_names_data) && length(other_names_data) > 0
+      !is.null(other_names_val) && length(other_names_val) > 0
     ) {
-      other_names_data
+      if (is.list(other_names_val)) other_names_val else list(other_names_val)
     } else {
       list(character(0))
     }

R/search.R

@@ -25,7 +25,10 @@
 #'
 #' @details
 #' This function queries the ORCID search endpoint:
-#' \code{https://pub.orcid.org/v3.0/search}
+#' \code{https://pub.orcid.org/v3.0/expanded-search}
+#'
+#' The expanded-search endpoint returns name information along with ORCID IDs,
+#' unlike the basic search endpoint which only returns identifiers.
 #'
 #' **Query Field Examples:**
 #' \itemize{
@@ -42,7 +45,7 @@
 #' \code{"family-name:Smith AND affiliation-org-name:Harvard"}
 #'
 #' @references
-#' ORCID API Search Documentation: \url{https://info.orcid.org/documentation/integration-guide/searching-the-orcid-registry/}
+#' ORCID API Search Documentation: \url{https://info.orcid.org/documentation/api-tutorials/api-tutorial-searching-the-orcid-registry/}
 #'
 #' @seealso
 #' \code{\link{orcid_search}} for a more user-friendly interface,
@@ -102,7 +105,7 @@ orcid <- function(query = NULL, rows = 10, start = 0, token = NULL, ...) {
   }
 
   # Construct URL
-  url <- paste0(orcid_base_url(), "/search")
+  url <- paste0(orcid_base_url(), "/expanded-search")
 
   # Build request
   req <- httr2::request(url) |>
@@ -200,7 +203,7 @@ orcid <- function(query = NULL, rows = 10, start = 0, token = NULL, ...) {
 #' @details
 #' This function constructs a Solr query from the provided parameters and
 #' calls \code{\link{orcid}} internally. Multiple parameters are combined
-#' with AND logic.
+#' with AND logic. Uses the expanded-search endpoint to return name information.
 #'
 #' @examples
 #' \dontrun{

README.Rmd

@@ -17,11 +17,13 @@ knitr::opts_chunk$set(
 
 [![Lifecycle:
 experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
-[![CRAN
-status](https://www.r-pkg.org/badges/version/orcidtr)](https://CRAN.R-project.org/package=orcidtr)
+
+<!-- [![CRAN
+status](https://www.r-pkg.org/badges/version/orcidtr)](https://CRAN.R-project.org/package=orcidtr) -->
+
 [![R-CMD-check](https://github.com/lorenzoFabbri/orcidtr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/lorenzoFabbri/orcidtr/actions/workflows/R-CMD-check.yaml)
-[![codecov](https://codecov.io/gh/lorenzoFabbri/orcidtr/branch/main/graph/badge.svg)](https://codecov.io/gh/lorenzoFabbri/orcidtr)
-[![Buy Me a Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=epilorenzo&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/epilorenzo)
+[![codecov](https://codecov.io/gh/lorenzoFabbri/orcidtr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/lorenzoFabbri/orcidtr)
+[![Buy Me a Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=epilorenzo&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://buymeacoffee.com/epilorenzo)
 
 <!-- badges: end -->
 

README.md

@@ -5,12 +5,14 @@
 
 [![Lifecycle:
 experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
-[![CRAN
-status](https://www.r-pkg.org/badges/version/orcidtr)](https://CRAN.R-project.org/package=orcidtr)
+
+<!-- [![CRAN
+status](https://www.r-pkg.org/badges/version/orcidtr)](https://CRAN.R-project.org/package=orcidtr) -->
+
 [![R-CMD-check](https://github.com/lorenzoFabbri/orcidtr/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/lorenzoFabbri/orcidtr/actions/workflows/R-CMD-check.yaml)
-[![codecov](https://codecov.io/gh/lorenzoFabbri/orcidtr/branch/main/graph/badge.svg)](https://codecov.io/gh/lorenzoFabbri/orcidtr)
+[![codecov](https://codecov.io/gh/lorenzoFabbri/orcidtr/branch/main/graph/badge.svg)](https://app.codecov.io/gh/lorenzoFabbri/orcidtr)
 [![Buy Me a
-Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=epilorenzo&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://www.buymeacoffee.com/epilorenzo)
+Coffee](https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=☕&slug=epilorenzo&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff)](https://buymeacoffee.com/epilorenzo)
 
 <!-- badges: end -->
 

inst/WORDLIST

@@ -0,0 +1,24 @@
+CMD
+codecov
+Hadley
+httr
+https
+iDs
+Lifecycle
+OAuth
+orcid
+ORCiD
+ORCID
+ORCIDs
+ORCID's
+preprint
+preprints
+README
+recognitions
+ResearcherID
+rorcid
+roxygen
+Scopus
+Solr
+Wickham's
+XXXX