async-firefly 1.0.0

data/lib/async/firefly/data.rb

@@ -0,0 +1,37 @@
+require_relative "page"
+
+module Async
+  module Firefly
+    module Data
+      def bulk_update_transactions(query)
+        self.discard(self.with(path: "v1/data/bulk/transactions", parameters: {query: query}), nil, method: :post)
+      end
+
+      def destroy!(objects, unused: nil)
+        self.discard(self.with(path: "v1/data/destroy", parameters: {objects: objects, unused: unused}.compact))
+      end
+
+      def purge! = self.discard(self.with(path: "v1/data/purge"))
+
+      def export_accounts(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/accounts", parameters: parameters))
+
+      def export_bills(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/bills", parameters: parameters))
+
+      def export_subscriptions(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/subscriptions", parameters: parameters))
+
+      def export_budgets(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/budgets", parameters: parameters))
+
+      def export_categories(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/categories", parameters: parameters))
+
+      def export_piggy_banks(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/piggy-banks", parameters: parameters))
+
+      def export_recurring(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/recurring", parameters: parameters))
+
+      def export_rules(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/rules", parameters: parameters))
+
+      def export_tags(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/tags", parameters: parameters))
+
+      def export_transactions(**parameters) = self.fetch(Download, self.with(path: "v1/data/export/transactions", parameters: parameters))
+    end
+  end
+end

data/lib/async/firefly/error.rb

@@ -0,0 +1,57 @@
+require "async/rest/error"
+
+module Async
+  module Firefly
+    class Error < StandardError
+    end
+
+    class Failure < Async::REST::ResponseError
+      def self.for(response)
+        self.new(response, self.problem_for(self.payload_of(response)))
+      end
+
+      def self.payload_of(response)
+        response.read
+      rescue StandardError => error
+        error.message
+      end
+
+      def self.problem_for(payload)
+        case payload
+        in Hash => problem
+          problem
+        else
+          {message: payload.to_s}
+        end
+      end
+
+      def self.summary_of(problem)
+        problem[:message] || problem[:exception] || problem.inspect
+      end
+
+      def initialize(response, problem = {})
+        super(response)
+
+        @problem = problem
+      end
+
+      attr :problem
+
+      def message = self.status.to_s + ": " + self.class.summary_of(@problem)
+
+      def to_s = self.message
+
+      def status = @response.status
+
+      def retry_after = @response.headers["retry-after"]
+
+      def detail = @problem[:message]
+
+      def exception_class = @problem[:exception]
+
+      def errors = @problem.fetch(:errors, {})
+
+      def invalid? = !self.errors.empty?
+    end
+  end
+end

data/lib/async/firefly/escape.rb

@@ -0,0 +1,9 @@
+require "protocol/url/encoding"
+
+module Async
+  module Firefly
+    def self.escape(value)
+      ::Protocol::URL::Encoding.escape(value.to_s)
+    end
+  end
+end

data/lib/async/firefly/exchange_rates.rb

@@ -0,0 +1,77 @@
+require_relative "page"
+
+module Async
+  module Firefly
+    class CurrencyExchangeRate < Representation
+      def created_at = self.attributes[:created_at]
+
+      def updated_at = self.attributes[:updated_at]
+
+      def from_currency_id = self.attributes[:from_currency_id]
+
+      def from_currency_name = self.attributes[:from_currency_name]
+
+      def from_currency_code = self.attributes[:from_currency_code]
+
+      def from_currency_symbol = self.attributes[:from_currency_symbol]
+
+      def from_currency_decimal_places = self.attributes[:from_currency_decimal_places]
+
+      def to_currency_id = self.attributes[:to_currency_id]
+
+      def to_currency_name = self.attributes[:to_currency_name]
+
+      def to_currency_code = self.attributes[:to_currency_code]
+
+      def to_currency_symbol = self.attributes[:to_currency_symbol]
+
+      def to_currency_decimal_places = self.attributes[:to_currency_decimal_places]
+
+      def rate = self.attributes[:rate]
+
+      def date = self.attributes[:date]
+
+      def update(payload) = self.submit(CurrencyExchangeRate, @resource, payload, method: :put)
+
+      def delete = self.discard(@resource)
+    end
+
+    class CurrencyExchangeRatePage < Page
+      MEMBER = CurrencyExchangeRate
+    end
+
+    class ExchangeRatePairPage < Page
+      MEMBER = CurrencyExchangeRate
+
+      def member_path(record) = "../../../exchange-rates/" + self.identifier(record, :id)
+    end
+
+    class ExchangeRateDatedPage < Page
+      MEMBER = CurrencyExchangeRate
+
+      def member_path(record) = "../../../../exchange-rates/" + self.identifier(record, :id)
+    end
+
+    module ExchangeRates
+      def exchange_rates(**parameters) = Collection.for(self, "v1/exchange-rates", CurrencyExchangeRatePage, **parameters)
+
+      def exchange_rate(id) = CurrencyExchangeRate.new(self.with(path: "v1/exchange-rates/" + Firefly.escape(id)))
+
+      def create_exchange_rate(payload) = self.submit(CurrencyExchangeRate, self.with(path: "v1/exchange-rates"), payload, identify: true)
+
+      def exchange_rates_between(from, to, **parameters) = Collection.for(self, "v1/exchange-rates/" + Firefly.escape(from) + "/" + Firefly.escape(to), ExchangeRatePairPage, **parameters)
+
+      def delete_exchange_rates_between(from, to) = self.discard(self.with(path: "v1/exchange-rates/" + Firefly.escape(from) + "/" + Firefly.escape(to)))
+
+      def exchange_rates_on(from, to, date, **parameters) = Collection.for(self, "v1/exchange-rates/" + Firefly.escape(from) + "/" + Firefly.escape(to) + "/" + Firefly.escape(date), ExchangeRateDatedPage, **parameters)
+
+      def update_exchange_rate_on(from, to, date, payload) = self.submit(CurrencyExchangeRate, self.with(path: "v1/exchange-rates/" + Firefly.escape(from) + "/" + Firefly.escape(to) + "/" + Firefly.escape(date)), payload, method: :put)
+
+      def delete_exchange_rate_on(from, to, date) = self.discard(self.with(path: "v1/exchange-rates/" + Firefly.escape(from) + "/" + Firefly.escape(to) + "/" + Firefly.escape(date)))
+
+      def create_exchange_rates_by_date(date, payload) = self.submit(CurrencyExchangeRatePage, self.with(path: "v1/exchange-rates/by-date/" + Firefly.escape(date)), payload, identify: nil)
+
+      def create_exchange_rates_by_pair(from, to, payload) = self.submit(CurrencyExchangeRatePage, self.with(path: "v1/exchange-rates/by-currencies/" + Firefly.escape(from) + "/" + Firefly.escape(to)), payload, identify: nil)
+    end
+  end
+end

data/lib/async/firefly/insight.rb

@@ -0,0 +1,185 @@
+require_relative "page"
+
+module Async
+  module Firefly
+    class InsightGroupEntry < Representation
+      def id = self.value[:id]
+
+      def name = self.value[:name]
+
+      def difference = self.value[:difference]
+
+      def difference_float = self.value[:difference_float]
+
+      def currency_id = self.value[:currency_id]
+
+      def currency_code = self.value[:currency_code]
+    end
+
+    class InsightTotalEntry < Representation
+      def difference = self.value[:difference]
+
+      def difference_float = self.value[:difference_float]
+
+      def currency_id = self.value[:currency_id]
+
+      def currency_code = self.value[:currency_code]
+    end
+
+    class InsightTransferEntry < Representation
+      def id = self.value[:id]
+
+      def name = self.value[:name]
+
+      def difference = self.value[:difference]
+
+      def difference_float = self.value[:difference_float]
+
+      def in = self.value[:in]
+
+      def in_float = self.value[:in_float]
+
+      def out = self.value[:out]
+
+      def out_float = self.value[:out_float]
+
+      def currency_id = self.value[:currency_id]
+
+      def currency_code = self.value[:currency_code]
+    end
+
+    class InsightGroup < Representation
+      include Enumerable
+
+      def each(&block)
+        if block
+          self.deconstruct.each{|record| block.call(InsightGroupEntry.new(@resource, value: record, metadata: self.metadata))}
+        else
+          self.to_enum(:each)
+        end
+      end
+    end
+
+    class InsightTotal < Representation
+      include Enumerable
+
+      def each(&block)
+        if block
+          self.deconstruct.each{|record| block.call(InsightTotalEntry.new(@resource, value: record, metadata: self.metadata))}
+        else
+          self.to_enum(:each)
+        end
+      end
+    end
+
+    class InsightTransfer < Representation
+      include Enumerable
+
+      def each(&block)
+        if block
+          self.deconstruct.each{|record| block.call(InsightTransferEntry.new(@resource, value: record, metadata: self.metadata))}
+        else
+          self.to_enum(:each)
+        end
+      end
+    end
+
+    module Insight
+      def expense_by_expense_account(start:, end:, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/expense/expense", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def expense_by_asset_account(start:, end:, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/expense/asset", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def income_by_revenue_account(start:, end:, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/income/revenue", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def income_by_asset_account(start:, end:, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/income/asset", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def transfer_by_asset_account(start:, end:, accounts: nil)
+        InsightTransfer.new(self.with(path: "v1/insight/transfer/asset", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def expense_by_bill(start:, end:, bills: nil, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/expense/bill", parameters: {start:, end:, bills:, accounts:}.compact))
+      end
+
+      def expense_without_bill(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/expense/no-bill", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def expense_by_budget(start:, end:, budgets: nil, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/expense/budget", parameters: {start:, end:, budgets:, accounts:}.compact))
+      end
+
+      def expense_without_budget(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/expense/no-budget", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def expense_by_category(start:, end:, categories: nil, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/expense/category", parameters: {start:, end:, categories:, accounts:}.compact))
+      end
+
+      def expense_without_category(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/expense/no-category", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def income_by_category(start:, end:, categories: nil, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/income/category", parameters: {start:, end:, categories:, accounts:}.compact))
+      end
+
+      def income_without_category(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/income/no-category", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def transfer_by_category(start:, end:, categories: nil, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/transfer/category", parameters: {start:, end:, categories:, accounts:}.compact))
+      end
+
+      def transfer_without_category(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/transfer/no-category", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def expense_by_tag(start:, end:, tags: nil, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/expense/tag", parameters: {start:, end:, tags:, accounts:}.compact))
+      end
+
+      def expense_without_tag(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/expense/no-tag", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def income_by_tag(start:, end:, tags: nil, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/income/tag", parameters: {start:, end:, tags:, accounts:}.compact))
+      end
+
+      def income_without_tag(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/income/no-tag", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def transfer_by_tag(start:, end:, tags: nil, accounts: nil)
+        InsightGroup.new(self.with(path: "v1/insight/transfer/tag", parameters: {start:, end:, tags:, accounts:}.compact))
+      end
+
+      def transfer_without_tag(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/transfer/no-tag", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def expense_total(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/expense/total", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def income_total(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/income/total", parameters: {start:, end:, accounts:}.compact))
+      end
+
+      def transfer_total(start:, end:, accounts: nil)
+        InsightTotal.new(self.with(path: "v1/insight/transfer/total", parameters: {start:, end:, accounts:}.compact))
+      end
+    end
+  end
+end

data/lib/async/firefly/links.rb

@@ -0,0 +1,69 @@
+require_relative "page"
+
+module Async
+  module Firefly
+    class LinkType < Representation
+      def name = self.attributes[:name]
+
+      def inward = self.attributes[:inward]
+
+      def outward = self.attributes[:outward]
+
+      def editable = self.attributes[:editable]
+
+      def transactions(**parameters) = Collection.for(@resource, "transactions", LinkTypeTransactionPage, **parameters)
+
+      def update(payload) = self.submit(LinkType, @resource, payload, method: :put)
+
+      def delete = self.discard(@resource)
+    end
+
+    class TransactionLink < Representation
+      def created_at = self.attributes[:created_at]
+
+      def updated_at = self.attributes[:updated_at]
+
+      def link_type_id = self.attributes[:link_type_id]
+
+      def link_type_name = self.attributes[:link_type_name]
+
+      def inward_id = self.attributes[:inward_id]
+
+      def outward_id = self.attributes[:outward_id]
+
+      def notes = self.attributes[:notes]
+
+      def update(payload) = self.submit(TransactionLink, @resource, payload, method: :put)
+
+      def delete = self.discard(@resource)
+    end
+
+    class LinkTypePage < Page
+      MEMBER = LinkType
+    end
+
+    class TransactionLinkPage < Page
+      MEMBER = TransactionLink
+    end
+
+    class LinkTypeTransactionPage < Page
+      def member_class = Transaction
+
+      def member_path(record) = "../../../transactions/" + self.identifier(record, :id)
+    end
+
+    module Links
+      def link_types(**parameters) = Collection.for(self, "v1/link-types", LinkTypePage, **parameters)
+
+      def link_type(id) = LinkType.new(self.with(path: "v1/link-types/" + Firefly.escape(id)))
+
+      def create_link_type(payload) = self.submit(LinkType, self.with(path: "v1/link-types"), payload, identify: true)
+
+      def transaction_links(**parameters) = Collection.for(self, "v1/transaction-links", TransactionLinkPage, **parameters)
+
+      def transaction_link(id) = TransactionLink.new(self.with(path: "v1/transaction-links/" + Firefly.escape(id)))
+
+      def create_transaction_link(payload) = self.submit(TransactionLink, self.with(path: "v1/transaction-links"), payload, identify: true)
+    end
+  end
+end

data/lib/async/firefly/nested.rb

@@ -0,0 +1,75 @@
+require_relative "page"
+
+module Async
+  module Firefly
+    class NestedPage < Page
+      def collection = raise NotImplementedError
+
+      def member_path(record) = "../../../" + self.collection + "/" + self.identifier(record, :id)
+    end
+
+    class NestedAccountPage < NestedPage
+      def member_class = Account
+
+      def collection = "accounts"
+    end
+
+    class NestedTransactionPage < NestedPage
+      def member_class = Transaction
+
+      def collection = "transactions"
+    end
+
+    class NestedAttachmentPage < NestedPage
+      def member_class = Attachment
+
+      def collection = "attachments"
+    end
+
+    class NestedPiggyBankPage < NestedPage
+      def member_class = PiggyBank
+
+      def collection = "piggy-banks"
+    end
+
+    class NestedBillPage < NestedPage
+      def member_class = Bill
+
+      def collection = "bills"
+    end
+
+    class NestedRulePage < NestedPage
+      def member_class = Rule
+
+      def collection = "rules"
+    end
+
+    class NestedRecurrencePage < NestedPage
+      def member_class = Recurrence
+
+      def collection = "recurrences"
+    end
+
+    class NestedAvailableBudgetPage < NestedPage
+      def member_class = AvailableBudget
+
+      def collection = "available-budgets"
+    end
+
+    class NestedExchangeRatePage < NestedPage
+      def member_class = CurrencyExchangeRate
+
+      def collection = "exchange-rates"
+    end
+
+    class NestedBudgetLimitPage < NestedPage
+      def member_class = BudgetLimit
+
+      def collection = "budget-limits"
+
+      def member_path(record)
+        "../../../budgets/" + self.identifier(record, :attributes, :budget_id) + "/limits/" + self.identifier(record, :id)
+      end
+    end
+  end
+end

data/lib/async/firefly/object_groups.rb

@@ -0,0 +1,33 @@
+require_relative "page"
+
+module Async
+  module Firefly
+    class ObjectGroup < Representation
+      def created_at = self.attributes[:created_at]
+
+      def updated_at = self.attributes[:updated_at]
+
+      def title = self.attributes[:title]
+
+      def order = self.attributes[:order]
+
+      def piggy_banks(**parameters) = Collection.for(@resource, "piggy-banks", NestedPiggyBankPage, **parameters)
+
+      def bills(**parameters) = Collection.for(@resource, "bills", NestedBillPage, **parameters)
+
+      def update(payload) = self.submit(ObjectGroup, @resource, payload, method: :put)
+
+      def delete = self.discard(@resource)
+    end
+
+    class ObjectGroupPage < Page
+      MEMBER = ObjectGroup
+    end
+
+    module ObjectGroups
+      def object_groups(**parameters) = Collection.for(self, "v1/object-groups", ObjectGroupPage, **parameters)
+
+      def object_group(id) = ObjectGroup.new(self.with(path: "v1/object-groups/" + Firefly.escape(id)))
+    end
+  end
+end

data/lib/async/firefly/page.rb

@@ -0,0 +1,139 @@
+require_relative "error"
+require_relative "representation"
+
+module Async
+  module Firefly
+    class Page < Representation
+      include Enumerable
+
+      MEMBER = Representation
+
+      def records
+        case self.value
+        in {data: Array => records}
+          records
+        else
+          []
+        end
+      end
+
+      def pagination
+        case self.value
+        in {meta: {pagination: Hash => pagination}}
+          pagination
+        else
+          {}
+        end
+      end
+
+      def total = self.pagination[:total].to_i
+
+      def per_page = self.pagination[:per_page].to_i
+
+      def current_page = self.pagination[:current_page].to_i
+
+      def total_pages = self.pagination[:total_pages].to_i
+
+      def last? = self.current_page >= [self.total_pages, 1].max
+
+      def empty? = self.records.empty?
+
+      def each(&block)
+        if block
+          self.records.each do |record|
+            block.call(self.member_for(record))
+          end
+        else
+          self.to_enum(:each)
+        end
+      end
+
+      def member_class = self.class::MEMBER
+
+      def member_path(record) = self.identifier(record, :id)
+
+      def identifier(record, *keys)
+        value = record.dig(*keys)
+
+        if value.nil? || value.to_s.empty?
+          raise Error, self.class.to_s + " cannot address a member: the response carried no " + keys.join(".")
+        end
+
+        Firefly.escape(value)
+      end
+
+      def member_resource(record)
+        @resource.with(path: self.member_path(record), parameters: nil, merge: false)
+      end
+
+      def member_for(record)
+        self.member_class.new(self.member_resource(record), value: {data: record}, metadata: self.metadata)
+      end
+    end
+
+    class Collection
+      include Enumerable
+
+      DEFAULT_LIMIT = 50
+
+      def self.for(parent, path, page_class, **parameters)
+        self.new(parent.with(path: path, parameters: parameters), page_class)
+      end
+
+      def initialize(resource, page_class)
+        @resource = resource
+        @page_class = page_class
+      end
+
+      attr :resource
+
+      attr :page_class
+
+      def each_page(limit: DEFAULT_LIMIT, &block)
+        if block
+          self.walk(limit, &block)
+        else
+          self.to_enum(:each_page, limit: limit)
+        end
+      end
+
+      def each(**options, &block)
+        if block
+          self.each_page(**options) do |page|
+            page.each(&block)
+          end
+        else
+          self.to_enum(:each, **options)
+        end
+      end
+
+      def page(number, limit: DEFAULT_LIMIT)
+        @page_class.new(@resource.with(parameters: {page: number, limit: limit}))
+      end
+
+      def total
+        self.page(1, limit: 1).total
+      end
+
+      def walk(limit, &block)
+        number = 1
+
+        while true
+          page = self.page(number, limit: limit)
+
+          if page.empty?
+            break
+          end
+
+          block.call(page)
+
+          if page.last?
+            break
+          end
+
+          number += 1
+        end
+      end
+    end
+  end
+end