tide-api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ec2c251ba56f87e5ccbc4d970ec642f52ca04d98fcb739da167baa200c9436b
-  data.tar.gz: 1690057695f361604045fcc386bc2538a85add4f2d0db8549d6650a5d93d212d
+  metadata.gz: '08178e48252d17a39c560d70c0d82cb68bb70c0eb7723789c34a927a0f6f585d'
+  data.tar.gz: ab105cfc9a5d77a36d8c2c256fc2ce43780333ac816d6593e275f506b2ab1b49
 SHA512:
-  metadata.gz: f47db1720338256d0b8c9019aca314e2f18b72d97360b9ca6c1af6114983bbeccefb53c3153984371712026691287b3fc0dce657e02a6d89da490a492e04863b
-  data.tar.gz: a79c51198faa008060a14385a6934cb5542d73c402e06f3fe6736301ca91bd4aa864a274ce657ef168748e3978d7cb72be40b3a237b9d6e3101c6fbed93d6061
+  metadata.gz: 9a50e7f1673260d44648ef43c65f15608ccb2e01f3b08b12433f0dbdbaf5fb8e5a29bd88cddf38f40636b8e70c754be9a84e731d87d1c04d800079d63cb0fbcc
+  data.tar.gz: 1b0c7f27c1b17f4cda5b4349dc41662ed19d7053b734839963eed9bcdcb5d04caf3ac42565389d3ab80da57a3e1eb3b170cd3a159c9e7a96391b2cdbce0c0458

data/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2019-06-30
+### Added
+- An HTTP server to capture Authentication Grant Codes from OAuth2 callbacks 
+
 ## [0.2.0] - 2019-06-30
 ### Added
 - Initial core business logic
@@ -11,3 +15,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [0.1.0] - 2019-05-26
 ### Added
 - Codebase maintenance tools
+
+[0.3.0]: https://github.com/wilsonsilva/tide-api/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/wilsonsilva/tide-api/compare/v0.1.0...v0.2.0

data/README.md

@@ -9,6 +9,20 @@
 
 Ruby interface to Tide's bank RESTful API.
 
+## Table of contents
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Authentication](#authentication)
+  - [Obtaining an Authorization Grant Code](#obtaining-an-azuthorization-grant-code)
+  - [Exchanging an Authorisation Grant for an Access Token](#exchanging-an-authorisation-grant-for-an-access-token)
+- [Fetching Companies](#fetching-companies)
+- [Fetching Accounts](#fetching-accounts)
+- [Fetching Transactions](#fetching-transactions)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -27,28 +41,69 @@ Or install it yourself as:
 
 ## Usage
 
-Tide uses `Access Tokens` to allow access to the API via OAuth 2. You can find more about authentication on 
-[the official API reference](https://tideapi.github.io/docs/#authentication).
+### Authentication
+
+Tide uses `Access Tokens` to allow access to the API via OAuth 2. Tide uses `Access Token`s to allow access to the
+API via OAuth 2. You can obtain an OAuth 2 `Access Toke`n by navigating to the below url, either in the web application
+or through an in-app browser window:
+
+`https://api.tide.co/tide-backend/oauth/index.html?redirect_url={url}&client_id={unique_id}`
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `redirect_uri` | string | Fully qualified URL to which `Authorisation Grants` will be delivered to. Grants will be delivered only on successful authorisation by resource owner. |
+| `client_id` | string | Unique identifier for the requester. |
+
+Once the page loads, the user needs to enter the unique email address, which is registered on their Tide account.
 
-Follow the documentation until you have an `Authorization Grant Code`. I'm developing a command-line utility to
-automate the authentication process.
+### Obtaining an Authorization Grant Code
+Use the bundled minimalistic AuthServer to automate the process above:
 
 ```ruby
 require 'tide/api'
+require 'tide/api/auth_server'
 
-client = Tide::API::Client.new
+server = Tide::API::AuthServer.new
+auth_grant_code = server.run
+```
+
+`Authorisation Grants` can only be used once off by the client, once used they are expired and cannot be used to issue
+new `Access Tokens`.
 
-# Authentication
-auth_grant_code = 'CBCAzT2L6A5oFZyE78R2TtYYtaJ60er0' 
+### Exchanging an Authorisation Grant for an Access Token
+Exchange the authorisation grant code with the method `fetch_tokens`:
+
+```ruby
+client = Tide::API::Client.new
 tokens = client.fetch_tokens(auth_grant_code)
 
-# Fetching companies
+# Tokens contains an access token and a refresh token
+tokens.access_token
+tokens.refresh_token
+````
+
+Fetch tokens will configure the client the behind the scenes to make authenticated requests.
+
+## Fetching Companies
+This method retrieves a collection of companies with the user. The user is determined from authorization header.
+
+```ruby
+client = Tide::API::Client.new
 companies = client.fetch_companies
+````
+
+## Fetching Accounts
+This method retrieves a collection of company accounts associated with the user. The user is determined from
+authorization header.
 
-# Fetch accounts
+```ruby
 accounts = client.fetch_accounts(companies.first.id)
+````
 
-# Fetch transactions 
+## Fetching Transactions
+This method retrieves a collection of an account's transactions:
+
+```ruby
 transactions = client.fetch_transactions(accounts.first.id)
 ```
 

data/bin/tide

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require 'tide/api'
+require 'tide/api/auth_server'
+
+server = Tide::API::AuthServer.new
+auth_grant_code = server.run
+
+puts auth_grant_code

data/lib/tide/api/auth_server.rb

@@ -0,0 +1,68 @@
+# typed: true
+require 'socket'
+
+module Tide
+  module API
+    # Receives an authorization grant code from the OAuth2 callback.
+    class AuthServer
+      # This is the ID shown in the authorization page of the mobile app
+      CLIENT_ID = 'tide-api-gem'.freeze
+      # Complete HTTP response
+      RESPONSE = "HTTP/1.1 200 OK\r\n" \
+                 "Content-Type: text/plain\r\n" \
+                 "Content-Length: 31\r\n" \
+                 "Connection: close\r\n" \
+                 "\r\n" \
+                 "You can now close this window.\n".freeze
+
+      def initialize
+        @server = TCPServer.new('localhost', 0)
+        @port = server.addr[1]
+      end
+
+      # Runs a tiny HTTP server to receive OAuth2 callbacks.
+      #
+      # @return [String] The authentication grant code from Tide.
+      #
+      def run
+        puts 'Waiting for the authorization code...'
+        request_auth_nonce
+
+        socket = server.accept
+        auth_nonce = extract_auth_nonce(socket.gets)
+
+        puts 'Authorization code received.'
+
+        socket.print RESPONSE
+        socket.close
+
+        auth_nonce
+      end
+
+      private
+
+      # @api private
+      def request_auth_nonce
+        system("open '#{auth_page_url}'")
+      end
+
+      # @api private
+      def redirect_url
+        "http://localhost:#{port}&client_id=#{CLIENT_ID}"
+      end
+
+      # @api private
+      def auth_page_url
+        "https://api.tide.co/tide-backend/oauth/index.html?redirect_url=#{redirect_url}"
+      end
+
+      # @api private
+      def extract_auth_nonce(http_response_line)
+        http_response_line.split('=').last.split.first
+      end
+
+      # @api private
+      attr_reader :server, :port
+    end
+  end
+end

data/lib/tide/api/version.rb

@@ -1,5 +1,5 @@
 module Tide
   module API
-    VERSION = '0.2.0'.freeze
+    VERSION = '0.3.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tide-api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Wilson Silva
@@ -343,8 +343,10 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- bin/tide
 - lib/tide/api.rb
 - lib/tide/api/account.rb
+- lib/tide/api/auth_server.rb
 - lib/tide/api/client.rb
 - lib/tide/api/company.rb
 - lib/tide/api/error.rb