mercury_banking 0.5.34

data/README.md

@@ -0,0 +1,244 @@
+# MercuryBanking
+
+Client library for talking to [Mercury API](https://docs.mercury.com/reference).
+
+This gem comes in handy when you want to access all of your bank accounts and their transactions histories or make payments to existing recipients in your Mercury account.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mercury_banking'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install mercury_banking
+
+## Usage
+
+First initialize client:
+
+```ruby
+require 'mercury_banking'
+
+# For single account
+client = Mercury::API.new("YOUR_API_KEY")
+
+# For multiple accounts
+multi_client = Mercury::Multi.new(['YOUR_API_KEY'])
+```
+
+Then call the API
+
+```ruby
+client.accounts
+
+multi_client.balances
+```
+
+### CLI Usage
+
+The gem also provides a command-line interface for interacting with Mercury Banking:
+
+```bash
+# Display all accounts
+mercury accounts
+
+# List transactions for an account
+mercury transactions ACCOUNT_ID_OR_NUMBER
+
+# Download all transactions as CSV files
+mercury transactions_download
+
+# Download transactions with custom options
+mercury transactions_download --output_dir=my_transactions --start_date=2023-01-01 --end_date=2023-12-31
+
+# Download transactions in beancount format
+mercury transactions_download --format=beancount
+
+# Download transactions in both CSV and beancount formats
+mercury transactions_download --format=both
+
+# Generate a balance sheet report
+mercury financials balancesheet
+
+# Generate a balance sheet report with custom options
+mercury financials balancesheet --format=beancount --start=2023-01-01 --end=2023-12-31 --verbose
+
+# Generate an income statement report
+mercury financials incomestatement
+```
+
+The `transactions_download` command will download all Mercury transactions in the format:
+```
+transactions/YEAR-MO-Mercury-ACCOUNT-ID.csv
+```
+
+For example: `transactions/2023-01-Mercury-123456789.csv`
+
+When using the `--format=beancount` option, it will create files in the format:
+```
+transactions/YEAR-MO-Mercury-ACCOUNT-ID.beancount
+```
+
+### API Usage
+
+For transferring money to a _registered_ recipient:
+
+```ruby
+client.transfer(
+    recipient_id: RECIPIENT_ID,
+    amount: 100000, # amount should be in USD
+    account_id: ACCOUNT_ID,
+    note: "TEST"
+    )
+```
+
+json response:
+
+```ruby
+{
+    "amount": 1000000,
+    "bankDescription": null,
+    "counterpartyId": "dd486506-d66b-11e9-8d8a-0b2e6a550f30",
+    "counterpartyName": "Fake P. Erson",
+    "counterpartyNickname": null,
+    "createdAt": "2019-09-13T21:17:15.974788Z",
+    "dashboardLink": "https://mercury.com/transactions/dd4896c0-d66b-11e9-8d8a-cf31cc71dda0",
+    "details": {
+        "address": null,
+        "domesticWireRoutingInfo": null,
+        "electronicRoutingInfo": null,
+        "internationalWireRoutingInfo": null
+    },
+    "estimatedDeliveryDate": "2019-09-13T21:17:17.387585Z",
+    "failedAt": null,
+    "id": "dd4896c0-d66b-11e9-8d8a-cf31cc71dda0",
+    "kind": "externalTransfer",
+    "note": null,
+    "externalMemo": null,
+    "postedAt": "2019-09-13T21:17:17.387585Z",
+    "reasonForFailure": null,
+    "status": "sent",
+    "feeId": null
+},
+```
+
+For transferring between two Mercury accounts:
+
+```ruby
+multi_client.transfer(
+    from: 'ACCOUNT_NAME_1',
+    to: 'ACCOUNT_NAME_2',
+    amount: 100000, # amount should be in USD
+    note: 'test',
+     email: 'test@gmail.com',
+     address: 'test address',
+     city: 'Minato',
+     region: 'Tokyo', # Either a two-letter US state code like "CA" for California or a free-form identification of a particular region worldwide
+     postal_code: '1110000',
+     country: 'JP' # ISO3166Alpha2 Ex. US, JP, etc.
+     )
+```
+
+json_response:
+
+```ruby
+{
+    "amount": 1000000,
+    "bankDescription": null,
+    "counterpartyId": "dd486506-d66b-11e9-8d8a-0b2e6a550f30",
+    "counterpartyName": "Fake P. Erson",
+    "counterpartyNickname": null,
+    "createdAt": "2019-09-13T21:17:15.974788Z",
+    "dashboardLink": "https://mercury.com/transactions/dd4896c0-d66b-11e9-8d8a-cf31cc71dda0",
+    "details": {
+        "address": null,
+        "domesticWireRoutingInfo": null,
+        "electronicRoutingInfo": null,
+        "internationalWireRoutingInfo": null
+    },
+    "estimatedDeliveryDate": "2019-09-13T21:17:17.387585Z",
+    "failedAt": null,
+    "id": "dd4896c0-d66b-11e9-8d8a-cf31cc71dda0",
+    "kind": "externalTransfer",
+    "note": null,
+    "externalMemo": null,
+    "postedAt": "2019-09-13T21:17:17.387585Z",
+    "reasonForFailure": null,
+    "status": "sent",
+    "feeId": null
+},
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Test
+
+We use [RSpec](http://rspec.info/) for testing. To run test use the following command:
+
+```ruby
+rspec spec
+```
+
+or
+
+```ruby
+rake spec
+```
+
+### Testing
+
+For running the test suite:
+
+1. Run `bundle install`
+2. Run `bundle exec rspec` to run the automated tests
+
+For manual testing:
+
+1. Run `bundle install`
+2. Rename `.env_test` to `.env`
+3. Inside the `.env` file, add your Mercury API key
+4. Use the CLI commands to interact with the Mercury API
+
+## ToDo
+
+- To cover all endpoints
+- Throw useful errors
+- Encryption
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`).
+3. Commit your changes (`git commit -am "Add new feature"`).
+4. Push to the branch (`git push origin my-new-feature`).
+5. Create a new Pull Request.
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/XenonIO/mercury-banking. 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/XenonIO/mercury-banking/blob/master/CODE_OF_CONDUCT.md).
+
+## Release Notes
+
+- v1.0.0: Initial major release.
+
+## Reference
+
+See [Mercury docs](https://docs.mercury.com/reference) for the complete list of endpoints.
+
+## 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 MercuryBanking project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/XenonIO/mercury-banking/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "mercury_banking"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/mercury

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+require 'thor'
+require 'mercury_banking'
+require 'dotenv/load'
+require 'json'
+require 'fileutils'
+require 'base64'
+require 'terminal-table'
+require 'time'
+require 'logger' # Explicitly require logger
+require 'securerandom'
+require 'mercury_banking/cli'
+require 'symmetric-encryption'
+
+# Start the CLI
+MercuryBanking::CLI::Main.start(ARGV) 

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/mercury_banking/api.rb

@@ -0,0 +1,184 @@
+module MercuryBanking
+  class API
+    def initialize(secret)
+      @api_key = secret
+    end
+
+    def get(path)
+      check_if_the_path_is_valid(path)
+      response = send_get_request_to_api(path)
+      body = parse_json(response)
+      validate_body(body, path)
+      body
+    end
+
+    def check_if_the_path_is_valid(path)
+      if path.nil? || path.empty?
+        raise 'Path cannot be empty'
+      elsif path[0] == '/'
+        raise "Path should not start with a /."
+      else
+        path
+      end
+    end
+
+    def send_get_request_to_api(path)
+      base_url = "https://backend.mercury.com/api/v1/"
+      url = URI.join(base_url, path)
+
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Get.new(url)
+      request.basic_auth @api_key, ''
+
+      http.request(request)
+    end
+
+    def parse_json(response)
+      JSON.parse(response.read_body)
+    end
+
+    def validate_body(body, path)
+      if body["errors"]
+        raise "#{@api_key} access to #{path} errored with #{body["errors"]["message"]}"
+      end
+      
+      body
+    end
+
+    def post(object, path)
+      check_if_the_path_is_valid(path)
+      response = send_post_request_to_api(object, path)
+      body = parse_json(response)
+      validate_body(body, path)
+      body
+    end
+
+    def send_post_request_to_api(object, path)
+      base_url = "https://backend.mercury.com/api/v1/"
+      url = URI.join(base_url, path)
+
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = true
+
+      request = Net::HTTP::Post.new(url)
+      request["accept"] = 'application/json'
+      request["content-type"] = 'application/json'
+      request.body = object.to_json
+
+      request.basic_auth @api_key, ''
+
+      http.request(request)
+    end
+
+    # Userland API
+    def accounts
+      get("accounts")["accounts"]
+    end
+
+    def get_account(account_id)
+      path = "account/#{account_id}"
+      get(path)
+    end
+
+    # Find account by account number
+    def find_account_by_number(account_number)
+      account = accounts.find { |a| a["accountNumber"] == account_number.to_s }
+      raise "Account with number #{account_number} not found" unless account
+      account
+    end
+
+    def balance(account_id)
+      account = get_account(account_id)
+      account['currentBalance']
+    end
+    
+    # /account/:id/transactions
+    def get_transactions(account_id, start_date = nil)
+      path = "account/#{account_id}/transactions"
+      path += "?start=#{start_date}" if start_date
+      get(path)["transactions"]
+    end
+    
+    # Get transactions from all accounts
+    def get_all_transactions(start_date = nil)
+      all_transactions = []
+      
+      accounts.each do |account|
+        begin
+          account_transactions = get_transactions(account["id"], start_date)
+          # Add account information to each transaction
+          account_transactions.each do |transaction|
+            transaction["accountName"] = account["name"]
+            transaction["accountId"] = account["id"]
+          end
+          all_transactions.concat(account_transactions)
+        rescue StandardError => e
+          puts "Warning: Could not fetch transactions for account #{account["name"]}: #{e.message}" unless ENV['MERCURY_SILENT']
+        end
+      end
+      
+      # Sort all transactions by date (newest first)
+      all_transactions.sort_by { |t| t["createdAt"] || "" }.reverse
+    end
+    
+    # /account/:id/transactions/:id
+    def transaction(account_id, transaction_id)
+      path = "account/#{account_id}/transaction/#{transaction_id}"
+      get(path)
+    end
+
+    def recipients
+      get("recipients")["recipients"]
+    end
+
+    def find_recipient(name:)
+      recipients.find { |r| r["name"] == name && r['status'] != 'deleted' }
+    end
+
+    def get_recipient(recipient_id)
+      path = "recipient/#{recipient_id}"
+      get(path)
+    end
+
+    def add_recipient(name:, address:, email:, city:, region:, postal_code:, country:, account_number:, routing_number:)
+      rec = MercuryBanking::Recipient.new(
+        name: name,
+        address: address,
+        email: email,
+        city: city,
+        region: region,
+        postal_code: postal_code,
+        country: country,
+        account_number: account_number,
+        routing_number: routing_number
+      )
+      post(rec.json, 'recipients')
+      new_recipient = find_recipient(name: name)
+      raise "Couldn't add account #{name}" unless new_recipient
+      puts "Successfully added #{new_recipient['name']}" if new_recipient
+    end
+
+    def update_recipient(name:, address:, email:, city:, region:, postal_code:, country:, account_number:, routing_number:, recipient_id:)
+      rec = MercuryBanking::Recipient.new(
+        name: name,
+        address: address,
+        email: email,
+        city: city,
+        region: region,
+        postal_code: postal_code,
+        country: country,
+        account_number: account_number,
+        routing_number: routing_number
+      )
+      post(rec.json, "recipient/#{recipient_id}")
+    end
+
+    def transfer(recipient_id:, amount:, account_id:, note: nil, external: nil)
+      payload = { recipientId: recipient_id, amount: amount, paymentMethod: 'ach',
+                  note: note, externalMemo: external, idempotencyKey: "#{recipient_id}-#{amount}-#{note}-#{external}" }
+      self.post(payload, "account/#{account_id}/transactions")
+    end
+  end
+end 

data/lib/mercury_banking/cli/accounts.rb

@@ -0,0 +1,61 @@
+module MercuryBanking
+  module CLI
+    # Module for account-related commands
+    module Accounts
+      # Add account-related commands to the CLI class
+      def self.included(base)
+        base.class_eval do
+          desc 'accounts', 'Display all accounts'
+          method_option :format, type: :string, default: 'table', enum: ['table', 'json'], desc: 'Output format (table or json)'
+          def accounts
+            with_api_client do |client|
+              accounts = client.accounts
+              
+              if options[:json] || options[:format] == 'json'
+                puts JSON.pretty_generate(accounts)
+              else
+                display_accounts_table(accounts)
+              end
+              
+              puts "You have #{accounts.count} account/s" unless options[:json]
+            end
+          end
+
+          desc 'balance ACCOUNT_ID_OR_NUMBER', "Display the current balance of an account (using account number from accounts table)"
+          def balance(account_identifier)
+            with_api_client do |client|
+              # Determine if we're dealing with an account ID or account number
+              account_id = nil
+              if account_identifier.match?(/^\d+$/) && !account_identifier.include?('-')
+                begin
+                  account = client.find_account_by_number(account_identifier)
+                  account_id = account["id"]
+                rescue => e
+                  # If not found by number, assume it's an ID
+                  account_id = account_identifier
+                  account = client.get_account(account_id)
+                end
+              else
+                account_id = account_identifier
+                account = client.get_account(account_id)
+              end
+              
+              balance = client.balance(account_id)
+              
+              if options[:json]
+                puts JSON.pretty_generate({
+                  'account_id' => account_id,
+                  'account_number' => account['accountNumber'],
+                  'name' => account['name'],
+                  'balance' => balance
+                })
+              else
+                puts "#{account['name']} (#{account['accountNumber']}): $#{format("%.2f", balance)}"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end 

data/lib/mercury_banking/cli/base.rb

@@ -0,0 +1,68 @@
+module MercuryBanking
+  module CLI
+    # Base module for CLI functionality
+    module Base
+      # Get API client with error handling
+      def with_api_client
+        api_key = get_api_key
+        raise "API key not found. Please run 'mercury set_key' first." unless api_key
+        
+        client = MercuryBanking::API.new(api_key)
+        yield client
+      rescue StandardError => e
+        if options[:json]
+          puts JSON.pretty_generate({ 'error' => e.message })
+        else
+          puts "Error: #{e.message}"
+        end
+        exit 1
+      end
+
+      # Get the API key from the encrypted storage
+      def get_api_key
+        config_path = File.join(Dir.home, '.mercury-banking', 'api_key.enc')
+        key_path = File.join(Dir.home, '.mercury-banking', 'key_config.json')
+        
+        unless File.exist?(config_path) && File.exist?(key_path)
+          raise "API key not found. Please run 'mercury set_key' first."
+        end
+        
+        begin
+          key_config = JSON.parse(File.read(key_path))
+          
+          # Initialize the SymmetricEncryption with the loaded cipher
+          cipher = SymmetricEncryption::Cipher.new(
+            key: Base64.strict_decode64(key_config['key']),
+            iv: Base64.strict_decode64(key_config['iv']),
+            cipher_name: key_config['cipher_name'] || 'aes-256-cbc'
+          )
+          
+          # Set the cipher as the primary one
+          SymmetricEncryption.cipher = cipher
+          
+          encrypted_key = File.read(config_path)
+          cipher.decrypt(encrypted_key)
+        rescue => e
+          puts "Error decrypting API key: #{e.message}"
+          exit 1
+        end
+      end
+
+      # Log transfer details
+      def log_transfer(from, to, amount, note, status)
+        log_dir = File.join(Dir.home, '.mercury-banking', 'logs')
+        FileUtils.mkdir_p(log_dir)
+        
+        log_file = File.join(log_dir, 'transfers.log')
+        File.open(log_file, 'a') do |f|
+          f.puts "#{Time.now.iso8601},\"#{from}\",\"#{to}\",\"#{amount}\",\"#{note}\",\"#{status}\""
+        end
+      end
+
+      # Check if a command exists in the system
+      def command_exists?(command)
+        system("which #{command} > /dev/null 2>&1")
+      end
+    end
+  end
+end