From 0d5805bdf8f03cc8344dfcc7c6869cdfe38bc5fd Mon Sep 17 00:00:00 2001
From: Tungle Duy <tungleduy.xyz@gmail.com>
Date: Sun, 14 Jun 2026 20:45:34 +0700
Subject: [PATCH] Add raw GET methods to Resource and Subscription models for
 unparsed responses

---
 lib/killbill_client/models/resource.rb     |  7 ++
 lib/killbill_client/models/subscription.rb | 10 +++
 spec/killbill_client/raw_response_spec.rb  | 93 ++++++++++++++++++++++
 3 files changed, 110 insertions(+)
 create mode 100644 spec/killbill_client/raw_response_spec.rb

diff --git a/lib/killbill_client/models/resource.rb b/lib/killbill_client/models/resource.rb
index 70e6ba9..c752f20 100644
--- a/lib/killbill_client/models/resource.rb
+++ b/lib/killbill_client/models/resource.rb
@@ -44,6 +44,13 @@ def get(uri, params = {}, options = {}, clazz = self)
           from_response clazz, response
         end
 
+        # Performs a GET request and returns the raw response body as received
+        # from Kill Bill, without any model parsing or re-serialization.
+        def raw_get(uri, params = {}, options = {})
+          response = KillBillClient::API.get uri, params, options
+          response.body
+        end
+
         def post(uri, body = nil, params = {}, options = {}, clazz = self)
           response = KillBillClient::API.post uri, body, params, options
           from_response clazz, response
diff --git a/lib/killbill_client/models/subscription.rb b/lib/killbill_client/models/subscription.rb
index ea1c050..12f993f 100644
--- a/lib/killbill_client/models/subscription.rb
+++ b/lib/killbill_client/models/subscription.rb
@@ -26,6 +26,16 @@ def find_by_id(subscription_id, audit = "NONE", options = {})
               options
         end
 
+        # Returns the raw JSON response body from Kill Bill for the given
+        # subscription, without any model parsing or re-serialization.
+        def find_raw_by_id(subscription_id, audit = "NONE", options = {})
+          raw_get "#{KILLBILL_API_ENTITLEMENT_PREFIX}/#{subscription_id}",
+                  {
+                    :audit => audit
+                  },
+                  options
+        end
+
         def find_by_external_key(external_key, audit = "NONE", options = {})
           get "#{KILLBILL_API_ENTITLEMENT_PREFIX}",
               {
diff --git a/spec/killbill_client/raw_response_spec.rb b/spec/killbill_client/raw_response_spec.rb
new file mode 100644
index 0000000..62a23ce
--- /dev/null
+++ b/spec/killbill_client/raw_response_spec.rb
@@ -0,0 +1,93 @@
+require 'spec_helper'
+
+describe 'Raw JSON responses' do
+  let(:raw_body) do
+    '{"subscriptionId":"abc-123","externalKey":"key-1","accountId":"acct-1","state":"ACTIVE"}'
+  end
+
+  let(:fake_response) do
+    response = double('Net::HTTPResponse')
+    allow(response).to receive(:body).and_return(raw_body)
+    response
+  end
+
+  describe KillBillClient::Model::Resource, '.raw_get' do
+    it 'returns the raw response body without parsing it into a model' do
+      uri = '/1.0/kb/some/endpoint'
+      params = { :foo => 'bar' }
+      options = { :api_key => 'k', :api_secret => 's' }
+
+      expect(KillBillClient::API).to receive(:get).with(uri, params, options).and_return(fake_response)
+      expect(KillBillClient::Model::Resource).not_to receive(:from_response)
+
+      result = KillBillClient::Model::Resource.raw_get(uri, params, options)
+
+      expect(result).to be_a(String)
+      expect(result).to eq(raw_body)
+    end
+
+    it 'defaults params and options to empty hashes' do
+      uri = '/1.0/kb/some/endpoint'
+
+      expect(KillBillClient::API).to receive(:get).with(uri, {}, {}).and_return(fake_response)
+
+      result = KillBillClient::Model::Resource.raw_get(uri)
+      expect(result).to eq(raw_body)
+    end
+
+    it 'propagates KillBillClient::API errors instead of swallowing them' do
+      uri = '/1.0/kb/missing'
+      api_request = double('Net::HTTPRequest')
+      api_response = double('Net::HTTPResponse',
+                            :code => '404',
+                            :body => '{"className":"NoSuchElementException"}')
+      response_error = KillBillClient::API::ResponseError.new(api_request, api_response)
+
+      expect(KillBillClient::API).to receive(:get).and_raise(response_error)
+
+      expect { KillBillClient::Model::Resource.raw_get(uri) }
+        .to raise_error(KillBillClient::API::ResponseError)
+    end
+  end
+
+  describe KillBillClient::Model::Subscription, '.find_raw_by_id' do
+    let(:subscription_id) { 'sub-1234' }
+    let(:expected_uri) { "/1.0/kb/subscriptions/#{subscription_id}" }
+
+    it 'GETs the subscription endpoint and returns the raw body' do
+      options = { :api_key => 'k', :api_secret => 's' }
+
+      expect(KillBillClient::API).to receive(:get)
+        .with(expected_uri, { :audit => 'NONE' }, options)
+        .and_return(fake_response)
+
+      result = KillBillClient::Model::Subscription.find_raw_by_id(subscription_id, 'NONE', options)
+
+      expect(result).to eq(raw_body)
+    end
+
+    it 'forwards the audit option to the API call' do
+      expect(KillBillClient::API).to receive(:get)
+        .with(expected_uri, { :audit => 'FULL' }, {})
+        .and_return(fake_response)
+
+      KillBillClient::Model::Subscription.find_raw_by_id(subscription_id, 'FULL')
+    end
+
+    it 'defaults the audit option to NONE' do
+      expect(KillBillClient::API).to receive(:get)
+        .with(expected_uri, { :audit => 'NONE' }, {})
+        .and_return(fake_response)
+
+      KillBillClient::Model::Subscription.find_raw_by_id(subscription_id)
+    end
+
+    it 'does not instantiate a Subscription model' do
+      expect(KillBillClient::API).to receive(:get).and_return(fake_response)
+      expect(KillBillClient::Model::Subscription).not_to receive(:from_response)
+      expect(KillBillClient::Model::Subscription).not_to receive(:from_json)
+
+      KillBillClient::Model::Subscription.find_raw_by_id(subscription_id)
+    end
+  end
+end