Add Transparency endpoint with Complete Response Letters support

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    open_fda_api (0.1.0)
+    open_fda_api (0.2.0)
       faraday (~> 2.0)
 
 GEM

README.md

@@ -64,6 +64,40 @@ client.other.substance_data_reports(args)
 
 # Tobacco API
 client.tobacco.problem_reports(args)
+
+# Transparency API
+client.transparency.complete_response_letters(args)
+```
+
+### Transparency — Complete Response Letters
+
+Complete Response Letters (CRLs) are issued by the FDA when a New Drug Application (NDA)
+or Biologics License Application (BLA) cannot be approved in its current form.
+
+```ruby
+client = OpenFdaApi::Client.new
+
+# Fetch the most recent CRL
+client.transparency.complete_response_letters(limit: 1)
+
+# Search by company name
+client.transparency.complete_response_letters(
+  search: [{ "company_name" => "Pfizer" }],
+  limit: 10
+)
+
+# Search by approver center and sort by letter date descending
+client.transparency.complete_response_letters(
+  search: [{ "approver_center" => "Center for Drug Evaluation and Research" }],
+  sort: [{ "letter_date" => "desc" }],
+  limit: 5
+)
+
+# Search for CRLs from a specific company OR a specific approver
+client.transparency.complete_response_letters(
+  search: [{ "company_name" => "Novartis" }, { "approver_name" => "John Doe" }],
+  limit: 10
+)
 ```
 
 ### Querying
@@ -116,12 +150,12 @@ To release a new version, update the version number in `version.rb`, and then ru
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/hebron-george/open_fda_api .
-This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/open_fda_api/blob/master/CODE_OF_CONDUCT.md).
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/hebron-george/open_fda_api/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the OpenFdaApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/open_fda_api/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the OpenFdaApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/hebron-george/open_fda_api/blob/main/CODE_OF_CONDUCT.md).

lib/open_fda_api.rb

@@ -14,6 +14,7 @@ class Error < StandardError; end
   autoload :Food, "open_fda_api/food"
   autoload :Other, "open_fda_api/other"
   autoload :Tobacco, "open_fda_api/tobacco"
+  autoload :Transparency, "open_fda_api/transparency"
   autoload :QueryInputs, "open_fda_api/query_inputs"
   autoload :QueryBuilder, "open_fda_api/query_builder"
 end

lib/open_fda_api/client.rb

@@ -39,6 +39,10 @@ def other
       OpenFdaApi::Other.new(self)
     end
 
+    def transparency
+      OpenFdaApi::Transparency.new(self)
+    end
+
     def connection
       @connection ||= Faraday.new(BASE_URL) do |conn|
         conn.request :json

lib/open_fda_api/transparency.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenFdaApi
+  # Interact with the Transparency API Endpoint:
+  #  - Complete Response Letters
+  class Transparency < Endpoint
+    # Complete Response Letters (CRL) are issued when the FDA determines it will not approve
+    # a New Drug Application (NDA) or Biologics License Application (BLA) in its current form.
+    #
+    # @param search [Array<Hash>] Search fields defined in https://open.fda.gov/apis/transparency/completeresponseletters/searchable-fields/
+    # @param sort   [Array<Hash>] Sort fields defined in https://open.fda.gov/apis/transparency/completeresponseletters/searchable-fields/
+    # @param count  [Array<Hash>] Count fields defined in https://open.fda.gov/apis/transparency/completeresponseletters/searchable-fields/
+    # @param skip   [Integer]     Number of results to skip
+    # @param limit  [Integer]     Number of results to return
+    # @return Response from the API parsed as JSON
+    def complete_response_letters(search: [], sort: [], count: [], skip: 0, limit: 1)
+      endpoint = "crl.json"
+      inputs   = build_inputs(search: search, sort: sort, count: count, skip: skip, limit: limit)
+      query    = build_query(inputs)
+      make_request(endpoint, query)
+    end
+
+    private
+
+    def endpoint_path
+      "/transparency"
+    end
+  end
+end

lib/open_fda_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OpenFdaApi
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

spec/fixtures/transparency/crl.json

@@ -0,0 +1,28 @@
+{
+  "meta": {
+    "disclaimer": "Do not rely on openFDA to make decisions regarding medical care. While we make every effort to ensure that data is accurate, you should assume all results are unvalidated. We may limit or otherwise restrict your access to the API in line with our Terms of Service.",
+    "terms": "https://open.fda.gov/terms/",
+    "license": "https://open.fda.gov/license/",
+    "last_updated": "2024-01-01",
+    "results": {
+      "skip": 0,
+      "limit": 1,
+      "total": 100
+    }
+  },
+  "results": [
+    {
+      "file_name": "example_crl.pdf",
+      "application_number": "NDA012345",
+      "letter_type": "COMPLETE RESPONSE",
+      "letter_date": "2023-06-15",
+      "company_name": "Example Pharmaceuticals Inc.",
+      "company_rep": "Jane Smith",
+      "company_address": "123 Pharma Way, New York, NY 10001",
+      "approver_name": "John Doe",
+      "approver_title": "Acting Deputy Director",
+      "approver_center": "Center for Drug Evaluation and Research",
+      "text": "We have completed our review of this application and have determined that we cannot approve this application in its present form."
+    }
+  ]
+}

spec/open_fda_api/client_spec.rb

@@ -26,4 +26,8 @@
   context "#other" do
     it { expect(instance.other).to be_a(OpenFdaApi::Other) }
   end
+
+  context "#transparency" do
+    it { expect(instance.transparency).to be_a(OpenFdaApi::Transparency) }
+  end
 end

spec/open_fda_api/transparency_spec.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+RSpec.describe OpenFdaApi::Transparency do
+  let(:instance) { client.transparency }
+  let(:client)   { OpenFdaApi::Client.new(adapter: :test, stubs: stub) }
+
+  context "#complete_response_letters API call" do
+    let(:stub) do
+      Faraday::Adapter::Test::Stubs.new do |stub|
+        stub.get("https://api.fda.gov/transparency/crl.json") do |_env|
+          [200, { "Content-Type" => "application/json" },
+           File.read("spec/fixtures/transparency/crl.json")]
+        end
+      end
+    end
+    subject(:complete_response_letters_call) { instance.complete_response_letters }
+
+    it "returns a response with meta and results" do
+      expect(complete_response_letters_call).to include("meta", "results")
+    end
+
+    it "returns complete response letter records" do
+      result = complete_response_letters_call["results"].first
+      expect(result).to include(
+        "application_number",
+        "letter_type",
+        "letter_date",
+        "company_name",
+        "approver_name",
+        "approver_center"
+      )
+    end
+  end
+end