increase 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c94e77f42a4d8c725f5518af02301564c6cbff71f90015063313e983aeac5124
-  data.tar.gz: 1d5ec565ec368dd713b47f18a41d5eb1363e624ef6792c05b87952f9fe368695
+  metadata.gz: a5ebc261a44d0f2a6df7fc703886dcc18e11a3c54bd2f04742b783e46fedc1f7
+  data.tar.gz: '073485629ad76bc387aa0a51d954a86bb93c9884bd90baccedeaa2cbf483efaa'
 SHA512:
-  metadata.gz: 4dd0a71c6eac5742ca4f63237eb8bbccffc8eefe625ce63e345b97cb4431b3cba04744e9acd426665757ab0d1240637a4fb02311cda84cbe7dc8fa1f2657c7bf
-  data.tar.gz: cba66503cbbeaf4fd7bdc6541899d033126a2efbc20a7ce70cb8b14f42a78a30628b3ea40b3da1b7b176e4d8219291d800846061f3004c70c2d0e96f4b548a64
+  metadata.gz: c2b625211c3e9ad0a7588caaeda4eaea8e216569e3efd2f83afaf48d0c8fed23794d0f8a0d4bdab6a0024115836cab51979a4731ea2fc0d4400de1967e0d9c93
+  data.tar.gz: ede3ef495349bf6c7cf6acacba84101061aa3740170ca3b7fea1fb4ec8e2c7e8df61b0654e9919e158c1bc033f8ef37ec4171538aeb485eae6f0c1f3cd619da5

data/OPENAPI_VERSION

@@ -0,0 +1 @@
+v0.0.1

data/README.md

@@ -1,6 +1,18 @@
 # Increase
 
-A Ruby API client for [Increase](https://increase.com/), a platform for Bare-Metal Banking APIs!
+A Ruby API client for [Increase](https://increase.com/), a platform for
+Bare-Metal Banking APIs!
+
+- [Installation](#installation)
+- [Usage](#usage)
+    - [Per-request Configuration](#per-request-configuration)
+    - [Pagination](#pagination)
+    - [Error Handling](#error-handling)
+    - [Configuration](#configuration)
+    - [File Uploads](#file-uploads)
+    - [Webhooks](#webhooks)
+    - [Idempotency](#idempotency)
+- [Development](#development)
 
 ## Installation
 
@@ -10,7 +22,8 @@ Install the gem and add to the application's Gemfile by executing:
 $ bundle add increase
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+If bundler is not being used to manage dependencies, install the gem by
+executing:
 
 ```sh
 $ gem install increase
@@ -43,32 +56,42 @@ Increase::AchTransfers.create(
 
 ### Per-request Configuration
 
-By default, the client will use the global API key and configurations. However, you can define a custom client to be
-used for per-request configuration.
+By default, the client will use the global API key and configurations. However,
+you can define a custom client to be used for per-request configuration.
 
-For example, you may want to have access to production and sandbox data at the same.
+For example, you may want access to production and sandbox data at the same
+time.
 
 ```ruby
 sandbox = Increase::Client.new(
-  api_key: 'time_is_money',
+  api_key: 'playing_it_safe',
   base_url: 'https://sandbox.increase.com'
 )
 
 # This request will use the `sandbox` client and its configurations
 Increase::Transactions.with_config(sandbox).list
-# => [{some sandbox transactions here}, {transaction}, {transaction}]
+# => [{some sandbox transactions here}, {transaction}, {transaction}, ...]
 
-# This request will still use the global configurations (where the API key is a production key)
+# This request will still use the global configurations (using production key)
 Increase::Transactions.list
-# => [{some production transactions here}, {transaction}, {transaction}]
+# => [{some production transactions here}, {transaction}, {transaction}, ...]
 ```
 
-See the [Configuration](#configuration) section for more information on the available configurations.
+Alternatively, directly passing as hash to `with_config` works too!
+
+```ruby
+Increase::Transactions.with_config(api_key: 'time_is_money', base_url: :sandbox).list
+# => [{some sandbox transactions here}, {transaction}, {transaction}, ...]
+```
+
+See the [Configuration](#configuration) section for more information on the
+available configurations.
 
 ### Pagination
 
-When listing resources (e.g. transactions), **Increase** limits the number of results per page to 100. Luckily, the
-client will automatically paginate through all the results for you!
+When listing resources (e.g. transactions), **Increase** limits the number of
+results per page to 100. Luckily, the client will automatically paginate through
+all the results for you!
 
 ```ruby
 Increase::Transactions.list(limit: :all) do |transactions|
@@ -78,38 +101,48 @@ end
 
 # Or, if you'd like a gargantuan array of all the transactions
 Increase::Transactions.list(limit: :all)
-Increase::Transactions.list(limit: 2_000)
+
+# You can also use the `next_cursor` to manually paginate through the results
+txns = Increase::Transactions.list(
+  limit: 2_000,
+  'created_at.after': '2022-01-15T06:34:23Z'
+)
+# => [{transaction}, {transaction}, {transaction}, ...]
+txns.next_cursor
+# => "eyJwb2NpdGlvbiI6eyJvZmlzZXQiOjEwMH0sIm3pbHRlclI6e319"
 ```
 
 Watch out for the rate limit!
 
 ### Error Handling
 
-Whenever you make an oopsies, the client will raise an error! Errors originating from the API will be a subclass
-of `Increase::ApiError`.
+Whenever you make an oopsie, the client will raise an error! Errors originating
+from the API will be a subclass of `Increase::ApiError`.
 
 ```ruby
 
 begin
-  Increase::Transactions.retrieve('transaction_1234abcd')
+  Increase::Transactions.retrieve('i_dont_exist')
 rescue Increase::ApiError => e
-  puts e.message # "[404: object_not_found_error] Could not find the specified object. No resource of type ..."
+  puts e.message # "[404: object_not_found_error] Could not find the ..."
   puts e.title # "Could not find the specified object."
-  puts e.detail # "No resource of type transaction was found with ID transaction_1234abcd."
+  puts e.detail # "No resource of type transaction was found with ID ..."
   puts e.status # 404
 
-  puts e.response # This contains the full response from the API, including headers! (its a Faraday::Env object)
+  puts e.response # This contains the full response, including headers!
+  # => #<Faraday::Response:0x000000010b1fe2b0 ...>
 
-  puts e.class # Increase::ObjectNotFoundError (it's a subclass of Increase::ApiError!)
+  puts e.class # Increase::ObjectNotFoundError (subclass of Increase::ApiError)
 end
 ```
 
-To disable this behavior, set `Increase.raise_api_errors = false`. Errors will then be returned as a normal response.
+To disable this behavior, set `Increase.raise_api_errors = false`. Errors will
+then be returned as a normal response.
 
 ```ruby
 Increase.raise_api_errors = false # Default: true
 
-Increase::Transactions.retrieve('transaction_1234abcd')
+Increase::Transactions.retrieve('i_dont_exist')
 # => {"status"=>404, "type"=>"object_not_found_error", ... }
 ```
 
@@ -129,21 +162,104 @@ Increase.api_key = 'terabytes_of_cash' # Default: nil (you'll need one tho!)
 Increase.base_url = :production # Default: :production
 Increase.raise_api_errors = true # Default: true
 
-# Or, you can use a block
+# Or, you can pass in a hash
+Increase.configure(api_key: 'just_my_two_cents')
+
+# Or, you can use a block!
 Increase.configure do |config|
   config.api_key = 'digital_dough'
-  config.base_url = :sandbox
-  config.raise_api_errors = false
+  config.base_url = :sandbox # Default: :production
+  config.raise_api_errors = false # Default: true
 end
+```
 
-# Or, you can pass in a hash
-Increase.configure(api_key: 'just_my_two_cents')
+If you are using Rails, the recommended way is to set your configurations as a
+block in an initializer.
+
+```ruby
+# config/initializers/increase.rb
+
+Increase.configure do |config|
+  # Your Increase API Key!
+  # Grab it from https://dashboard.increase.com/developers/api_keys
+  config.api_key = Rails.application.credentials.dig(:increase, :api_key)
+
+  # The base URL for Increase's API.
+  # You can use
+  # - :production (https://api.increase.com)
+  # - :sandbox (https://sandbox.increase.com)
+  # - or set an actual URL
+  config.base_url = Rails.env.production? ? :production : :sandbox
+
+  # Whether to raise an error when the API returns a non-2XX status.
+  # If disabled (false), the client will return the error response as a normal,
+  # instead of raising an error.
+  # 
+  # Learn more about...
+  # - Increase's errors: https://increase.com/documentation/api#errors
+  # - Error classes: https://github.com/garyhtou/increase-ruby/blob/main/lib/increase/errors.rb
+  config.raise_api_errors = true # Default: true
+end
+```
+
+### File Uploads
+
+```ruby
+# Creating a file of an image of a government-issued ID
+file_to_upload = Faraday::Multipart::FilePart.new(
+  '/path/to/file.jpg', # File path
+  'image/jpeg' # File name
+)
+
+Increase::Files.create(
+  purpose: 'identity_document',
+  file: file_to_upload
+) 
+```
+
+See [`faraday-multipart`](https://github.com/lostisland/faraday-multipart)'s
+documentation for more file upload options.
+
+### Webhooks
+
+**Increase**'s webhooks include a `Increase-Webhook-Signature` header for
+securing your webhook endpoint. Although not required, it's strongly recommended
+that you verify the signature to ensure the request is coming from **Increase**.
+
+Here is an example for Rails.
+
+```ruby
+
+class IncreaseController < ApplicationController
+  protect_from_forgery except: :webhook # Ignore CSRF checks
+
+  def webhook
+    payload = request.body.read
+    sig_header = request.headers['Increase-Webhook-Signature']
+    secret = Rails.application.credentials.dig(:increase, :webhook_secret)
+
+    Increase::Webhook::Signature.verify(
+      payload: payload,
+      signature_header: sig_header,
+      secret: secret
+    )
+
+    # It's a valid webhook! Do something with it...
+
+    render json: {success: true}
+
+  rescue Increase::WebhookSignatureVerificationError => e
+    render json: {error: 'Webhook signature verification failed'}, status: :bad_request
+  end
+end
 ```
 
 ### Idempotency
 
-**Increase** supports [idempotent requests](https://increase.com/documentation/api#idempotency) to allow for safely
-retrying requests without accidentally performing the same operation twice.
+**Increase**
+supports [idempotent requests](https://increase.com/documentation/api#idempotency)
+to allow for safely retrying requests without accidentally performing the same
+operation twice.
 
 ```ruby
 card = Increase::Cards.create(
@@ -159,35 +275,48 @@ card = Increase::Cards.create(
 )
 # => {"id"=>"card_1234abcd", "type"=>"card", ... }
 
-idempotent_replayed = card.response.headers['Idempotent-Replayed']
-# => "false"
+card.idempotent_replayed
+# => nil
+
+# Repeat the exact same request
+card = Increase::Cards.create(...)
+# => {"id"=>"card_1234abcd", "type"=>"card", ... }
+
+card.idempotent_replayed
+# => "true"
 ```
 
-Reusing the key in subsequent requests will return the same response code and body as the original request along with an
-additional HTTP header (Idempotent-Replayed: true). This applies to both success and error responses. In situations
-where your request results in a validation error, you'll need to update your request and retry with a new idempotency
-key.
+Reusing the key in subsequent requests will return the same response code and
+body as the original request along with an additional HTTP
+header (`Idempotent-Replayed: true`). This applies to both success and error
+responses. In situations where your request results in a validation error,
+you'll need to update your request and retry with a new idempotency key.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can
-also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then,
+run `rake spec` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
 
-You can also run `INCREASE_API_KEY=my_key_here INCREASE_BASE_URL=https://sandbox.increase.com bin/console` to run the
-console with your Increase sandbox API key pre-filled.
+You can also
+run `INCREASE_API_KEY=my_key_here INCREASE_BASE_URL=https://sandbox.increase.com bin/console`
+to run the console with your Increase sandbox API key pre-filled.
 
 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 the created tag, and push the `.gem` file
+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 the created tag, and push the `.gem` file
 to [rubygems.org](https://rubygems.org).
 
 Alternatively, use [`gem-release`](https://github.com/svenfuchs/gem-release) and
-run `gem bump --version patch|minor|major`. Then release the gem by running `bundle exec rake release`.
+run `gem bump --version patch|minor|major`. Then release the gem by
+running `bundle exec rake release`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/garyhtou/increase.
+Bug reports and pull requests are welcome on GitHub
+at https://github.com/garyhtou/increase.
 
 ## License
 
@@ -196,5 +325,5 @@ the [MIT License](https://github.com/garyhtou/increase-ruby/blob/main/LICENSE.tx
 
 ---
 
-Please note that this is not an official library written by **Increase**. Its written and maintained
-by [Gary Tou](https://garytou.com/) who just uses Increase at work!
+Please note that this is not an official library by **Increase**. This gem was
+created and maintained by [Gary Tou](https://garytou.com/).

data/bin/generate

@@ -0,0 +1,152 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# OpenAPI client generators for Ruby seem to be a bit of a mess. I'm
+# essentially writing my own crude generator here. It's not perfect, but it
+# gets the job done :)
+
+require 'bundler/setup'
+require 'irb'
+
+require 'json'
+require 'erb'
+require 'ostruct'
+require 'pry'
+
+spec = JSON.parse(File.read('openapi.json'))
+
+# Parse OpenAPI spec
+resources = Hash.new { |h, k| h[k] = [] } # Default value of new keys is []
+spec['paths'].each do |path, methods|
+  methods.each do |method, details|
+    name = details['x-tag'] # Resource name
+
+    endpoint = {
+      http_method: method.to_sym,
+      path: path.split('/').reject(&:empty?),
+      operation: details['operationId'].split('_').first.downcase,
+
+      # Extra info
+      details: details,
+    }
+
+    # Convert path params to symbols
+    path_params = details['parameters'].select { |p| p['in'] == 'path' }
+    endpoint[:path].map! do |p|
+      # Find path param for this segment
+      param = path_params.find { |param| "{#{param['name']}}" == p }
+      param ? param['name'].to_sym : p
+    end
+
+    # Handle case for "/groups/current".
+    # Changes operation from :retrieve to :current
+    if endpoint[:path].size > 1 && endpoint[:path].last.is_a?(String)
+      endpoint[:operation] = endpoint[:path].last.to_sym
+    end
+
+    # Add endpoint to resource
+    resources[name] << endpoint
+  end
+end
+
+# Write OpenAPI version to file
+api_version = spec['info']['version']
+File.open('OPENAPI_VERSION', 'w') do |file|
+  file.write("v#{api_version}")
+end
+
+# Clear resources directory
+Dir.glob('lib/increase/resources/*.rb').each do |file|
+  File.delete(file)
+end
+
+# Generate code
+OPERATION_ALIASES = [
+  {
+    name: 'create',
+    operation: 'create',
+    http_method: :post,
+    path_regex: /^\w+$/
+  },
+  {
+    name: 'list',
+    operation: 'list',
+    http_method: :get,
+    path_regex: /^\w+$/
+  },
+  {
+    name: 'update',
+    operation: 'update',
+    http_method: :patch,
+    path_regex: /^\w+\/\w+_id$/
+  },
+  {
+    name: 'retrieve',
+    operation: 'retrieve',
+    http_method: :get,
+    path_regex: /^\w+\/\w+_id$/
+  }
+]
+
+template = File.read('generate/resource.rb.erb')
+render = ERB.new(template, trim_mode: '-')
+
+resources.delete('Simulations') # TODO
+
+resources.each do |name, operations|
+  # Convert name to class name (pascal case with no special characters)
+  class_name = name.split(/[\s\W]/).map(&:capitalize).join
+
+  # Resource type
+  resource_type = operations.first[:path].first
+
+  # Format operations
+  ops = operations.each do |op|
+    # Try to find an alias for this operation
+    op_alias = OPERATION_ALIASES.find do |alias_op|
+      op[:operation] == alias_op[:operation] &&
+        op[:http_method] == alias_op[:http_method] &&
+        alias_op[:path_regex].match(op[:path].join('/'))
+    end
+    op.merge!(alias: op_alias&.dig(:name))
+
+    # Check to make sure path doesn't not contain more than 1 param
+    if op[:path].select { |p| p.is_a?(Symbol) }.size > 1
+      raise StandardError, "Multiple path params for #{name} #{op[:path].inspect}"
+    end
+
+    # Remove resource root path segment
+    op[:path].shift
+    if op[:path].size == 1
+      op[:path] = op[:path].first
+    end
+  end
+
+  # Check operation uniqueness
+  if ops.map { |op| op[:operation] }.uniq.size != ops.size
+    raise StandardError, "Duplicate operations for #{name}"
+  end
+
+  # Render template
+  namespace = OpenStruct.new(
+    class_name: class_name,
+    name: name,
+    api_name: resource_type,
+    operations: ops
+  )
+  contents = render.result(namespace.instance_eval { binding })
+
+  # Write to file
+  File.open("lib/increase/resources/#{resource_type}.rb", 'w') do |file|
+    file.write(contents)
+  end
+
+  # Print messages
+  puts "Generated #{class_name}"
+  ops.each do |op|
+    puts "  #{op[:operation]}"
+  end
+  puts
+end
+
+raise "TODO Reminder: Handle special case for Increase::Files.create"

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/generate/resource.rb.erb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "increase/resource"
+
+module Increase
+  class <%= class_name %> < Resource
+    NAME = <%= name.inspect %>
+    API_NAME = <%= api_name.inspect %>
+
+    <%- operations.each do |op| -%>
+    # <%= op[:details]['summary'] %>
+    <%- if op[:alias] -%>
+    <%= op[:alias] -%>
+    <%- else -%>
+    endpoint <%= op[:operation].inspect %>, <%= op[:http_method].inspect %>, path: <%= op[:path].inspect -%>
+    <%- end -%><%# close if %>
+    <%- end %><%# close loop %>  end
+end

data/lib/increase/client.rb

@@ -4,6 +4,7 @@ require "increase/configuration"
 
 require "faraday"
 require "faraday/follow_redirects"
+require "faraday/multipart"
 
 # Custom Faraday Middleware to handle raising errors
 require "faraday/raise_increase_api_error"
@@ -32,6 +33,7 @@ module Increase
         }
       ) do |f|
         f.request :json
+        f.request :multipart
 
         if @configuration.raise_api_errors
           # This custom middleware for raising Increase API errors must be

data/lib/increase/configuration.rb

@@ -22,7 +22,7 @@ module Increase
       if config.is_a?(Hash)
         config.each do |key, value|
           unless respond_to?("#{key}=")
-            raise Error, "Invalid configuration key: #{key}"
+            raise ArgumentError, "Invalid configuration: #{key}"
           end
           public_send("#{key}=", value)
         end