freeagentrb 0.1.4 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. checksums.yaml +4 -4
  2. data/.env.example +3 -1
  3. data/CHANGELOG.md +65 -0
  4. data/Gemfile +3 -3
  5. data/Gemfile.lock +78 -61
  6. data/README.md +747 -3
  7. data/bin/console +2 -0
  8. data/bin/fixtures +148 -0
  9. data/freeagentrb.gemspec +4 -5
  10. data/lib/free_agent/client.rb +164 -4
  11. data/lib/free_agent/error_generator.rb +4 -3
  12. data/lib/free_agent/oauth.rb +48 -0
  13. data/lib/free_agent/object.rb +113 -17
  14. data/lib/free_agent/objects/account_lock.rb +4 -0
  15. data/lib/free_agent/objects/account_manager.rb +4 -0
  16. data/lib/free_agent/objects/balance_sheet.rb +4 -0
  17. data/lib/free_agent/objects/bank_feed.rb +4 -0
  18. data/lib/free_agent/objects/bank_transaction.rb +7 -12
  19. data/lib/free_agent/objects/bill.rb +1 -0
  20. data/lib/free_agent/objects/capital_asset.rb +4 -0
  21. data/lib/free_agent/objects/capital_asset_type.rb +4 -0
  22. data/lib/free_agent/objects/cashflow.rb +5 -0
  23. data/lib/free_agent/objects/cis_band.rb +4 -0
  24. data/lib/free_agent/objects/cis_settings.rb +4 -0
  25. data/lib/free_agent/objects/corporation_tax_return.rb +5 -0
  26. data/lib/free_agent/objects/credit_note.rb +1 -0
  27. data/lib/free_agent/objects/credit_note_reconciliation.rb +5 -0
  28. data/lib/free_agent/objects/estimate.rb +1 -0
  29. data/lib/free_agent/objects/expense.rb +5 -0
  30. data/lib/free_agent/objects/final_accounts_report.rb +4 -0
  31. data/lib/free_agent/objects/hire_purchase.rb +4 -0
  32. data/lib/free_agent/objects/invoice.rb +1 -9
  33. data/lib/free_agent/objects/journal_set.rb +4 -0
  34. data/lib/free_agent/objects/note.rb +4 -0
  35. data/lib/free_agent/objects/payroll_period.rb +4 -0
  36. data/lib/free_agent/objects/payroll_profile.rb +5 -0
  37. data/lib/free_agent/objects/practice.rb +4 -0
  38. data/lib/free_agent/objects/practice_client.rb +4 -0
  39. data/lib/free_agent/objects/price_list_item.rb +5 -0
  40. data/lib/free_agent/objects/profit_and_loss.rb +6 -0
  41. data/lib/free_agent/objects/property.rb +4 -0
  42. data/lib/free_agent/objects/recurring_invoice.rb +5 -0
  43. data/lib/free_agent/objects/sales_tax_period.rb +4 -0
  44. data/lib/free_agent/objects/self_assessment_return.rb +4 -0
  45. data/lib/free_agent/objects/stock_item.rb +5 -0
  46. data/lib/free_agent/objects/tax_timeline_item.rb +5 -0
  47. data/lib/free_agent/objects/timeline_item.rb +5 -0
  48. data/lib/free_agent/objects/transaction.rb +5 -0
  49. data/lib/free_agent/objects/trial_balance_item.rb +5 -0
  50. data/lib/free_agent/objects/vat_return.rb +4 -0
  51. data/lib/free_agent/rate_limiter.rb +67 -0
  52. data/lib/free_agent/resource.rb +6 -2
  53. data/lib/free_agent/resources/account_locks.rb +24 -0
  54. data/lib/free_agent/resources/account_managers.rb +19 -0
  55. data/lib/free_agent/resources/balance_sheet.rb +15 -0
  56. data/lib/free_agent/resources/bank_accounts.rb +5 -7
  57. data/lib/free_agent/resources/bank_feeds.rb +13 -0
  58. data/lib/free_agent/resources/bank_transaction_explanations.rb +41 -1
  59. data/lib/free_agent/resources/bank_transactions.rb +1 -1
  60. data/lib/free_agent/resources/capital_asset_types.rb +28 -0
  61. data/lib/free_agent/resources/capital_assets.rb +14 -0
  62. data/lib/free_agent/resources/cashflow.rb +8 -0
  63. data/lib/free_agent/resources/categories.rb +33 -0
  64. data/lib/free_agent/resources/cis_bands.rb +8 -0
  65. data/lib/free_agent/resources/cis_settings.rb +15 -0
  66. data/lib/free_agent/resources/clients.rb +8 -0
  67. data/lib/free_agent/resources/company.rb +12 -0
  68. data/lib/free_agent/resources/contacts.rb +2 -2
  69. data/lib/free_agent/resources/corporation_tax_returns.rb +34 -0
  70. data/lib/free_agent/resources/credit_note_reconciliations.rb +31 -0
  71. data/lib/free_agent/resources/credit_notes.rb +0 -10
  72. data/lib/free_agent/resources/email_addresses.rb +9 -0
  73. data/lib/free_agent/resources/estimate_items.rb +3 -4
  74. data/lib/free_agent/resources/estimates.rb +30 -3
  75. data/lib/free_agent/resources/expenses.rb +45 -0
  76. data/lib/free_agent/resources/final_accounts_reports.rb +24 -0
  77. data/lib/free_agent/resources/hire_purchases.rb +13 -0
  78. data/lib/free_agent/resources/invoices.rb +22 -0
  79. data/lib/free_agent/resources/journal_sets.rb +37 -0
  80. data/lib/free_agent/resources/notes.rb +37 -0
  81. data/lib/free_agent/resources/payroll.rb +32 -0
  82. data/lib/free_agent/resources/payroll_profiles.rb +9 -0
  83. data/lib/free_agent/resources/practice.rb +10 -0
  84. data/lib/free_agent/resources/price_list_items.rb +30 -0
  85. data/lib/free_agent/resources/profit_and_loss.rb +10 -0
  86. data/lib/free_agent/resources/projects.rb +2 -2
  87. data/lib/free_agent/resources/properties.rb +29 -0
  88. data/lib/free_agent/resources/recurring_invoices.rb +23 -0
  89. data/lib/free_agent/resources/sales_tax_periods.rb +37 -0
  90. data/lib/free_agent/resources/self_assessment_returns.rb +36 -0
  91. data/lib/free_agent/resources/stock_items.rb +13 -0
  92. data/lib/free_agent/resources/tasks.rb +5 -4
  93. data/lib/free_agent/resources/timeslips.rb +20 -3
  94. data/lib/free_agent/resources/transactions.rb +15 -0
  95. data/lib/free_agent/resources/trial_balance.rb +13 -0
  96. data/lib/free_agent/resources/users.rb +3 -3
  97. data/lib/free_agent/resources/vat_returns.rb +35 -0
  98. data/lib/free_agent/version.rb +1 -1
  99. data/lib/free_agent.rb +67 -0
  100. metadata +83 -24
data/bin/console CHANGED
@@ -16,6 +16,8 @@ require 'dotenv/load'
16
16
 
17
17
  # @access_token = Igdb::AccessToken.new(client_id: ENV["CLIENT_ID"], client_secret: ENV["CLIENT_SECRET"])
18
18
 
19
+ @oauth = FreeAgent::OAuth.new(sandbox: true, client_id: ENV["FREEAGENT_CLIENT_ID"], client_secret: ENV["FREEAGENT_CLIENT_SECRET"])
20
+
19
21
  @client = FreeAgent::Client.new(access_token: ENV["ACCESS_TOKEN"], sandbox: true)
20
22
 
21
23
  require "irb"
data/bin/fixtures ADDED
@@ -0,0 +1,148 @@
1
+ #!/usr/bin/env ruby
2
+ # Downloads the example JSON responses from the FreeAgent API docs into
3
+ # test/fixtures, so tests run against the responses FreeAgent documents.
4
+ #
5
+ # bin/fixtures # every page
6
+ # bin/fixtures contacts bills # just these pages
7
+ #
8
+ # Each endpoint heading on a page becomes a file named after it, e.g. the
9
+ # "List all contacts" example is saved to test/fixtures/contacts/list_all_contacts.json.
10
+
11
+ require "net/http"
12
+ require "json"
13
+ require "fileutils"
14
+ require "cgi/escape"
15
+
16
+ DOCS_URL = "https://dev.freeagent.com/docs".freeze
17
+ FIXTURES_DIR = File.expand_path("../test/fixtures", __dir__).freeze
18
+
19
+ # Doc pages with API endpoints. Pages that are pure reference material, like
20
+ # currencies or sales_tax, are left out. A version is given for pages that
21
+ # only document their endpoints under a newer API version.
22
+ PAGES = {
23
+ "account_locks" => nil,
24
+ "accountancy_practice_api" => nil,
25
+ "attachments" => nil,
26
+ "balance_sheet" => nil,
27
+ "bank_accounts" => nil,
28
+ "bank_feeds" => nil,
29
+ "bank_transaction_explanation_attachments" => "2026-09-01",
30
+ "bank_transaction_explanations" => nil,
31
+ "bank_transactions" => nil,
32
+ "bills" => nil,
33
+ "capital_asset_types" => nil,
34
+ "capital_assets" => nil,
35
+ "cashflow" => nil,
36
+ "categories" => nil,
37
+ "cis_bands" => nil,
38
+ "cis_settings" => nil,
39
+ "company" => nil,
40
+ "contacts" => nil,
41
+ "corporation_tax_returns" => nil,
42
+ "credit_note_reconciliations" => nil,
43
+ "credit_notes" => nil,
44
+ "email_addresses" => nil,
45
+ "estimates" => nil,
46
+ "expenses" => nil,
47
+ "final_accounts_reports" => nil,
48
+ "hire_purchases" => nil,
49
+ "income_tax_returns" => nil, # self assessment returns
50
+ "invoices" => nil,
51
+ "journal_sets" => nil,
52
+ "notes" => nil,
53
+ "oauth" => nil,
54
+ "payroll" => nil,
55
+ "payroll_profiles" => nil,
56
+ "price_list_items" => nil,
57
+ "profit_and_loss" => nil,
58
+ "projects" => nil,
59
+ "properties" => nil,
60
+ "recurring_invoices" => nil,
61
+ "sales_tax_periods" => nil,
62
+ "stock_items" => nil,
63
+ "tasks" => nil,
64
+ "timeslips" => nil,
65
+ "transactions" => nil,
66
+ "trial_balance" => nil,
67
+ "users" => nil,
68
+ "vat_returns" => nil
69
+ }.freeze
70
+
71
+ def fetch(page, version)
72
+ uri = URI("#{DOCS_URL}/#{page}")
73
+ uri.query = "version=#{version}" if version
74
+ response = Net::HTTP.get_response(uri)
75
+ raise "#{uri} returned #{response.code}" unless response.is_a?(Net::HTTPSuccess)
76
+
77
+ response.body.force_encoding("UTF-8")
78
+ end
79
+
80
+ def text(html)
81
+ CGI.unescapeHTML(html.gsub(/<[^>]+>/, "")).strip
82
+ end
83
+
84
+ # Some examples in the docs aren't quite JSON, so strip the "..." placeholders,
85
+ # whole-line // comments and trailing commas they use before parsing
86
+ def parse(code)
87
+ JSON.parse(code)
88
+ rescue JSON::ParserError
89
+ cleaned = code.lines.reject { |line| line.strip == "..." || line.strip.start_with?("//") }.join
90
+ JSON.parse(cleaned.gsub(/,(\s*[\]}])/, "\\1"))
91
+ end
92
+
93
+ def slug(heading)
94
+ heading.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/\A_|_\z/, "")
95
+ end
96
+
97
+ # Yields [heading, json] for the first JSON example after each "Status:" block
98
+ def examples(html)
99
+ heading = nil
100
+ awaiting_response = false
101
+
102
+ html.scan(%r{<h2[^>]*>(.*?)</h2>|<pre[^>]*>(.*?)</pre>}m) do |h2, pre|
103
+ if h2
104
+ heading = text(h2)
105
+ awaiting_response = false
106
+ next
107
+ end
108
+
109
+ code = text(pre)
110
+ if code.start_with?("Status:")
111
+ awaiting_response = true
112
+ elsif awaiting_response && heading && code.start_with?("{", "[")
113
+ awaiting_response = false
114
+ yield heading, code
115
+ end
116
+ end
117
+ end
118
+
119
+ pages = ARGV.empty? ? PAGES.keys : ARGV
120
+ failures = []
121
+
122
+ pages.each do |page|
123
+ html = fetch(page, PAGES[page])
124
+ dir = File.join(FIXTURES_DIR, page)
125
+ names = Hash.new(0)
126
+
127
+ examples(html) do |heading, code|
128
+ name = slug(heading)
129
+ names[name] += 1
130
+ name = "#{name}_#{names[name]}" if names[name] > 1
131
+
132
+ begin
133
+ json = JSON.pretty_generate(parse(code))
134
+ rescue JSON::ParserError => e
135
+ failures << "#{page}/#{name}: #{e.message.lines.first.strip}"
136
+ next
137
+ end
138
+
139
+ FileUtils.mkdir_p(dir)
140
+ File.write(File.join(dir, "#{name}.json"), "#{json}\n")
141
+ puts "#{page}/#{name}.json"
142
+ end
143
+ end
144
+
145
+ unless failures.empty?
146
+ warn "\nThese examples aren't valid JSON, so were skipped:"
147
+ failures.each { |failure| warn " #{failure}" }
148
+ end
data/freeagentrb.gemspec CHANGED
@@ -8,14 +8,14 @@ Gem::Specification.new do |spec|
8
8
  spec.authors = [ "Dean Perry" ]
9
9
  spec.email = [ "dean@deanpcmad.com" ]
10
10
 
11
- spec.summary = "Ruby library for the FreeAgent v2 API"
11
+ spec.summary = "The easiest and most complete Ruby library for the FreeAgent v2 API"
12
12
  spec.homepage = "https://deanpcmad.com"
13
13
 
14
14
  spec.license = "MIT"
15
- spec.required_ruby_version = ">= 2.6.0"
15
+ spec.required_ruby_version = ">= 3.3.0"
16
16
 
17
17
  spec.metadata["homepage_uri"] = spec.homepage
18
- spec.metadata["source_code_uri"] = "https://github.com/deanpcmad/freeagentrb"
18
+ spec.metadata["source_code_uri"] = "https://github.com/d34ndev/freeagentrb"
19
19
 
20
20
  # Specify which files should be added to the gem when it is released.
21
21
  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -26,7 +26,6 @@ Gem::Specification.new do |spec|
26
26
  end
27
27
  spec.require_paths = [ "lib" ]
28
28
 
29
- spec.add_dependency "faraday", "~> 2.11"
29
+ spec.add_dependency "faraday", ">= 2.14.3", "< 3"
30
30
  spec.add_dependency "faraday-multipart", "~> 1.0"
31
- spec.add_dependency "ostruct", "~> 0.6.0"
32
31
  end
@@ -3,15 +3,39 @@ module FreeAgent
3
3
  BASE_URL = "https://api.freeagent.com/v2"
4
4
  SANDBOX_BASE_URL = "https://api.sandbox.freeagent.com/v2"
5
5
 
6
- attr_reader :access_token, :sandbox, :adapter
6
+ attr_reader :access_token, :sandbox, :subdomain, :api_version, :adapter, :rate_limiter
7
7
 
8
- def initialize(access_token:, sandbox: false, adapter: Faraday.default_adapter, stubs: nil)
8
+ # api_version is sent as the X-Api-Version header, a date such as
9
+ # "2026-09-01". Without it, FreeAgent serves each endpoint's original version.
10
+ def initialize(access_token:, sandbox: false, subdomain: nil, api_version: nil, adapter: Faraday.default_adapter, stubs: nil, logger: nil, enable_rate_limit_test: false)
9
11
  @access_token = access_token
10
12
  @sandbox = sandbox
13
+ @subdomain = subdomain
14
+ @api_version = api_version
11
15
  @adapter = adapter
16
+ @logger = logger
17
+ @enable_rate_limit_test = enable_rate_limit_test
12
18
 
13
19
  # Test stubs for requests
14
20
  @stubs = stubs
21
+
22
+ # Initialize rate limiter
23
+ @rate_limiter = FreeAgent::RateLimiter.new(logger: logger)
24
+ end
25
+
26
+ # Returns a new client scoped to one of the practice's clients, so that
27
+ # requests are made on their behalf via the X-Subdomain header.
28
+ def on_behalf_of(subdomain)
29
+ self.class.new(
30
+ access_token: access_token,
31
+ sandbox: sandbox,
32
+ subdomain: subdomain,
33
+ api_version: api_version,
34
+ adapter: adapter,
35
+ stubs: @stubs,
36
+ logger: @logger,
37
+ enable_rate_limit_test: @enable_rate_limit_test
38
+ )
15
39
  end
16
40
 
17
41
  def company
@@ -78,6 +102,130 @@ module FreeAgent
78
102
  CategoriesResource.new(self)
79
103
  end
80
104
 
105
+ def expenses
106
+ ExpensesResource.new(self)
107
+ end
108
+
109
+ def clients
110
+ ClientsResource.new(self)
111
+ end
112
+
113
+ def account_managers
114
+ AccountManagersResource.new(self)
115
+ end
116
+
117
+ def practice
118
+ PracticeResource.new(self)
119
+ end
120
+
121
+ def recurring_invoices
122
+ RecurringInvoicesResource.new(self)
123
+ end
124
+
125
+ def price_list_items
126
+ PriceListItemsResource.new(self)
127
+ end
128
+
129
+ def credit_note_reconciliations
130
+ CreditNoteReconciliationsResource.new(self)
131
+ end
132
+
133
+ def stock_items
134
+ StockItemsResource.new(self)
135
+ end
136
+
137
+ def journal_sets
138
+ JournalSetsResource.new(self)
139
+ end
140
+
141
+ def transactions
142
+ TransactionsResource.new(self)
143
+ end
144
+
145
+ def notes
146
+ NotesResource.new(self)
147
+ end
148
+
149
+ def bank_feeds
150
+ BankFeedsResource.new(self)
151
+ end
152
+
153
+ def email_addresses
154
+ EmailAddressesResource.new(self)
155
+ end
156
+
157
+ def account_locks
158
+ AccountLocksResource.new(self)
159
+ end
160
+
161
+ def capital_assets
162
+ CapitalAssetsResource.new(self)
163
+ end
164
+
165
+ def capital_asset_types
166
+ CapitalAssetTypesResource.new(self)
167
+ end
168
+
169
+ def hire_purchases
170
+ HirePurchasesResource.new(self)
171
+ end
172
+
173
+ def balance_sheet
174
+ BalanceSheetResource.new(self)
175
+ end
176
+
177
+ def profit_and_loss
178
+ ProfitAndLossResource.new(self)
179
+ end
180
+
181
+ def trial_balance
182
+ TrialBalanceResource.new(self)
183
+ end
184
+
185
+ def cashflow
186
+ CashflowResource.new(self)
187
+ end
188
+
189
+ def final_accounts_reports
190
+ FinalAccountsReportsResource.new(self)
191
+ end
192
+
193
+ def vat_returns
194
+ VatReturnsResource.new(self)
195
+ end
196
+
197
+ def corporation_tax_returns
198
+ CorporationTaxReturnsResource.new(self)
199
+ end
200
+
201
+ def self_assessment_returns
202
+ SelfAssessmentReturnsResource.new(self)
203
+ end
204
+
205
+ def sales_tax_periods
206
+ SalesTaxPeriodsResource.new(self)
207
+ end
208
+
209
+ def cis_bands
210
+ CisBandsResource.new(self)
211
+ end
212
+
213
+ def cis_settings
214
+ CisSettingsResource.new(self)
215
+ end
216
+
217
+ def payroll
218
+ PayrollResource.new(self)
219
+ end
220
+
221
+ def payroll_profiles
222
+ PayrollProfilesResource.new(self)
223
+ end
224
+
225
+ def properties
226
+ PropertiesResource.new(self)
227
+ end
228
+
81
229
  def connection
82
230
  url = (sandbox == true ? SANDBOX_BASE_URL : BASE_URL)
83
231
  @connection ||= Faraday.new(url) do |conn|
@@ -86,9 +234,17 @@ module FreeAgent
86
234
  conn.response :json
87
235
 
88
236
  conn.headers = {
89
- "User-Agent" => "freeagentrb/v#{VERSION} (github.com/deanpcmad/freeagentrb)"
237
+ "User-Agent" => "freeagentrb/v#{VERSION} (github.com/d34ndev/freeagentrb)"
90
238
  }
91
239
 
240
+ # Make requests on behalf of a practice client
241
+ conn.headers["X-Subdomain"] = subdomain if subdomain
242
+
243
+ conn.headers["X-Api-Version"] = api_version if api_version
244
+
245
+ # Add X-RateLimit-Test header if enabled (for testing in sandbox)
246
+ conn.headers["X-RateLimit-Test"] = "true" if @enable_rate_limit_test
247
+
92
248
  conn.adapter adapter, @stubs
93
249
  end
94
250
  end
@@ -96,9 +252,13 @@ module FreeAgent
96
252
  # Uses Faraday Multipart (lostisland/faraday-multipart)
97
253
  def connection_upload
98
254
  url = (sandbox == true ? SANDBOX_BASE_URL : BASE_URL)
99
- @connection ||= Faraday.new(url) do |conn|
255
+ @connection_upload ||= Faraday.new(url) do |conn|
100
256
  conn.request :authorization, :Bearer, access_token
101
257
  conn.request :multipart
258
+
259
+ conn.headers["User-Agent"] = "freeagentrb/v#{VERSION} (github.com/d34ndev/freeagentrb)"
260
+ conn.headers["X-Subdomain"] = subdomain if subdomain
261
+ conn.headers["X-Api-Version"] = api_version if api_version
102
262
  end
103
263
  end
104
264
  end
@@ -15,6 +15,7 @@ module FreeAgent
15
15
 
16
16
  # Parse the FreeAgent error code and message from the response body
17
17
  def set_freeagent_error_values
18
+ return unless @response_body.is_a?(Hash)
18
19
  if @response_body.dig("errors") && @response_body.dig("errors").is_a?(Array)
19
20
  @freeagent_error_message = @response_body.dig("errors").map { |error| error["message"] }.join(", ")
20
21
  elsif @response_body.dig("errors", "error", "message")
@@ -24,10 +25,10 @@ module FreeAgent
24
25
  end
25
26
  end
26
27
 
28
+ # Some errors, such as a 409 when deleting a sent invoice, come with no
29
+ # body at all
27
30
  def error_message
28
- @freeagent_error_message || @response_body.dig("error")
29
- rescue NoMethodError
30
- "An unknown error occurred."
31
+ @freeagent_error_message || (@response_body["error"] if @response_body.is_a?(Hash)) || "An unknown error occurred."
31
32
  end
32
33
 
33
34
  def build_message
@@ -0,0 +1,48 @@
1
+ module FreeAgent
2
+ class OAuth
3
+ attr_reader :sandbox, :client_id, :client_secret
4
+
5
+ def initialize(sandbox: true, client_id:, client_secret:)
6
+ @sandbox = sandbox
7
+ @client_id = client_id
8
+ @client_secret = client_secret
9
+
10
+ @base_url = sandbox ? "https://api.sandbox.freeagent.com/v2/" : "https://api.freeagent.com/v2/"
11
+ end
12
+
13
+ def authorise_url(redirect:, state: nil)
14
+ url = "#{@base_url}/approve_app?response_type=code&client_id=#{client_id}&redirect_uri=#{redirect}"
15
+ url += "&state=#{state}" if state
16
+ url
17
+ end
18
+
19
+ def token(code:, redirect:)
20
+ send_request(url: "#{@base_url}/token_endpoint", body: {
21
+ client_id: client_id,
22
+ client_secret: client_secret,
23
+ grant_type: "authorization_code",
24
+ code: code,
25
+ redirect_uri: redirect
26
+ })
27
+ end
28
+
29
+ def refresh(refresh_token:)
30
+ send_request(url: "#{@base_url}/token_endpoint", body: {
31
+ client_id: client_id,
32
+ client_secret: client_secret,
33
+ grant_type: "refresh_token",
34
+ refresh_token: refresh_token
35
+ })
36
+ end
37
+
38
+ private
39
+
40
+ def send_request(url:, body:)
41
+ response = Faraday.post(url, body)
42
+
43
+ return false if response.status != 200
44
+
45
+ FreeAgent::Object.new(JSON.parse(response.body))
46
+ end
47
+ end
48
+ end
@@ -1,24 +1,120 @@
1
- require "ostruct"
2
-
3
1
  module FreeAgent
4
- class Object < OpenStruct
5
- def initialize(attributes)
6
- super to_ostruct(attributes)
7
-
8
- # The FreeAgent API doesn't send an ID so generate it from the URL
9
- if attributes["url"]
10
- number = attributes["url"].match(/\d{2,}/)
11
- self.id = number[0] unless number.nil?
2
+ # A lightweight wrapper around API response data. Attributes can be read with dot notation
3
+ # (object.name) or like a hash (object[:name] or object["name"]). Nested hashes are wrapped too.
4
+ class Object
5
+ # Declares attributes the API sends as strings which should be exposed as
6
+ # floats, e.g. decimal_attributes :total_value
7
+ def self.decimal_attributes(*names)
8
+ @decimal_attributes = names.map(&:to_s)
9
+ end
10
+
11
+ def self.decimal_attribute_names
12
+ @decimal_attributes || []
13
+ end
14
+
15
+ def initialize(attributes = {})
16
+ @attributes = {}
17
+ (attributes || {}).each { |key, val| self[key] = val }
18
+
19
+ # The FreeAgent API doesn't send an ID so take it from the end of the URL
20
+ if self[:url].is_a?(String)
21
+ number = self[:url].match(%r{/(\d+)\z})
22
+ self[:id] = number[1] unless number.nil?
23
+ end
24
+
25
+ self.class.decimal_attribute_names.each do |name|
26
+ value = self[name]
27
+ next if value.nil? || value.to_s.empty?
28
+
29
+ self[name] = BigDecimal(value.to_s).to_f
30
+ end
31
+ end
32
+
33
+ def [](key)
34
+ @attributes[key.to_sym]
35
+ end
36
+
37
+ def []=(key, val)
38
+ @attributes[key.to_sym] = wrap(val)
39
+ end
40
+
41
+ def key?(key)
42
+ @attributes.key?(key.to_sym)
43
+ end
44
+
45
+ def dig(key, *rest)
46
+ val = self[key]
47
+ rest.empty? || val.nil? ? val : val.dig(*rest)
48
+ end
49
+
50
+ def each_pair(&block)
51
+ return enum_for(:each_pair) unless block_given?
52
+
53
+ @attributes.each_pair(&block)
54
+ self
55
+ end
56
+
57
+ # Returns the attributes as a hash, with nested objects converted to hashes too,
58
+ # so the result can be serialized
59
+ def to_h(&block)
60
+ hash = @attributes.transform_values { |val| unwrap(val) }
61
+ block ? hash.to_h(&block) : hash
62
+ end
63
+
64
+ def as_json(*)
65
+ to_h
66
+ end
67
+
68
+ def to_json(*args)
69
+ to_h.to_json(*args)
70
+ end
71
+
72
+ def ==(other)
73
+ other.is_a?(FreeAgent::Object) && to_h == other.to_h
74
+ end
75
+ alias eql? ==
76
+
77
+ def hash
78
+ to_h.hash
79
+ end
80
+
81
+ def inspect
82
+ attrs = @attributes.map { |key, val| "#{key}=#{val.inspect}" }.join(", ")
83
+ "#<#{self.class.name}#{" " unless attrs.empty?}#{attrs}>"
84
+ end
85
+ alias to_s inspect
86
+
87
+ private
88
+
89
+ # Unknown attributes return nil, like a hash
90
+ def method_missing(name, *args)
91
+ if name.end_with?("=") && args.size == 1
92
+ self[name.to_s.chomp("=")] = args.first
93
+ elsif args.empty? && !name.end_with?("=", "?", "!")
94
+ self[name]
95
+ else
96
+ super
97
+ end
98
+ end
99
+
100
+ def respond_to_missing?(name, include_private = false)
101
+ key?(name.to_s.chomp("=")) || super
102
+ end
103
+
104
+ def wrap(val)
105
+ case val
106
+ when FreeAgent::Object then val
107
+ when Hash then FreeAgent::Object.new(val)
108
+ when Array then val.map { |v| wrap(v) }
109
+ else val
12
110
  end
13
111
  end
14
112
 
15
- def to_ostruct(obj)
16
- if obj.is_a?(Hash)
17
- OpenStruct.new(obj.map { |key, val| [ key, to_ostruct(val) ] }.to_h)
18
- elsif obj.is_a?(Array)
19
- obj.map { |o| to_ostruct(o) }
20
- else # Assumed to be a primitive value
21
- obj
113
+ def unwrap(val)
114
+ case val
115
+ when FreeAgent::Object then val.to_h
116
+ when Array then val.map { |v| unwrap(v) }
117
+ else val
22
118
  end
23
119
  end
24
120
  end
@@ -0,0 +1,4 @@
1
+ module FreeAgent
2
+ class AccountLock < Object
3
+ end
4
+ end
@@ -0,0 +1,4 @@
1
+ module FreeAgent
2
+ class AccountManager < Object
3
+ end
4
+ end
@@ -0,0 +1,4 @@
1
+ module FreeAgent
2
+ class BalanceSheet < Object
3
+ end
4
+ end
@@ -0,0 +1,4 @@
1
+ module FreeAgent
2
+ class BankFeed < Object
3
+ end
4
+ end
@@ -1,19 +1,14 @@
1
1
  module FreeAgent
2
2
  class BankTransaction < Object
3
- def initialize(attributes)
4
- super to_ostruct(attributes)
3
+ decimal_attributes :amount, :unexplained_amount
5
4
 
6
- # Convert amounts to BigDecimal
7
- self.amount = BigDecimal(self.amount.to_s).to_f if self.amount
8
- self.unexplained_amount = BigDecimal(self.unexplained_amount.to_s).to_f if self.unexplained_amount
5
+ def initialize(attributes)
6
+ super
9
7
 
10
- # Convert amounts in bank_transaction_explanations to BigDecimal
11
- if self.bank_transaction_explanations
12
- self.bank_transaction_explanations.each do |explanation|
13
- explanation.id = explanation.url.match(/\d{2,}/)[0] if explanation.url
14
- explanation.gross_value = BigDecimal(explanation.gross_value.to_s).to_f if explanation.gross_value
15
- explanation.foreign_currency_value = BigDecimal(explanation.foreign_currency_value.to_s).to_f if explanation.foreign_currency_value
16
- explanation.transfer_value = BigDecimal(explanation.transfer_value.to_s).to_f if explanation.transfer_value
8
+ # Convert amounts in bank_transaction_explanations to floats
9
+ bank_transaction_explanations&.each do |explanation|
10
+ %i[gross_value foreign_currency_value transfer_value].each do |name|
11
+ explanation[name] = BigDecimal(explanation[name].to_s).to_f if explanation[name]
17
12
  end
18
13
  end
19
14
  end
@@ -1,4 +1,5 @@
1
1
  module FreeAgent
2
2
  class Bill < Object
3
+ decimal_attributes :net_value, :total_value, :paid_value, :due_value, :sales_tax_value
3
4
  end
4
5
  end
@@ -0,0 +1,4 @@
1
+ module FreeAgent
2
+ class CapitalAsset < Object
3
+ end
4
+ end
@@ -0,0 +1,4 @@
1
+ module FreeAgent
2
+ class CapitalAssetType < Object
3
+ end
4
+ end
@@ -0,0 +1,5 @@
1
+ module FreeAgent
2
+ class Cashflow < Object
3
+ decimal_attributes :balance
4
+ end
5
+ end
@@ -0,0 +1,4 @@
1
+ module FreeAgent
2
+ class CisBand < Object
3
+ end
4
+ end
@@ -0,0 +1,4 @@
1
+ module FreeAgent
2
+ class CisSettings < Object
3
+ end
4
+ end