bitpay-sdk 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 05ceac9c5a451d327ccaca3d7d5df7b4b791612e
-  data.tar.gz: 8bd0c8fd5d09f22b9a90dfcb8dd80ea841b70b4f
+  metadata.gz: a2250870a264044316b2cc449c5b9e03adafc8e4
+  data.tar.gz: fddc03975809e69617b2b5f0f489f21a7c4e9d63
 SHA512:
-  metadata.gz: 35f0005e156651cf165e3ae64bd42feecca410d7a9ac01dc0dcf3fd4c1e9596cbfe3d45de8c7a98214f95d0fe9ac8fca1a5e96707dbfd2064db9f5abd477353d
-  data.tar.gz: 431badf6d99383c1670af5f60599186a6c830e62953de356c93e913dedcc6d5738d588de75aadb1cdcc10e45a4edb31ea215845fc6d584d037012842a28f86bd
+  metadata.gz: b379b23455f8df1a27b07d701c8c21153414463e5e14a45325e560890958233a23073ef2529fd6cfabf0dac36911647e4f08efc94db4f7fb2c856c6a5a2c8330
+  data.tar.gz: 429da072948807f64bcf7a1a6600068cb08fabdc8928e48811be3bcfdba07a5527d032405be1fb2a2e3f4d13478f4b07f6f8ed3f9a52de92d9a68fc72b7d2671

data/.gitignore

@@ -7,3 +7,4 @@ pkg
 .ruby-gemset
 *.swo
 *.swp
+bitpaykey.pem

data/.travis.yml

@@ -1,3 +1,2 @@
 rvm:
-  - 2.1.0
-
+- 2.1.0

data/README.md

@@ -1,62 +1,187 @@
-# BitPay Library for Ruby [![](https://secure.travis-ci.org/bitpay/ruby-client.png)](http://travis-ci.org/bitpay/ruby-client)
+# BitPay Library for Ruby [![](https://secure.travis-ci.org/bitpay/ruby-client.png)](http://travis-ci.org/bitpay/ruby-client) [![Gem Version](https://badge.fury.io/rb/bitpay-sdk.svg)](http://badge.fury.io/rb/bitpay-sdk)
 Powerful, flexible, lightweight interface to the BitPay Bitcoin Payment Gateway API.
 
+The `bitpay-sdk` gem provides all the programattic tools required to implement a ruby client application for the BitPay REST API.  For developers who prefer the ease of command-line pairing during the development or deployment process, BitPay provides a complementary [Ruby CLI gem](https://github.com/bitpay/ruby-cli) which can be used in conjunction with this gem.
+
 ## Installation
 
-    gem install bitpay-sdk
-    
+```bash
+gem install bitpay-sdk
+```
+
 In your Gemfile:
 
-    gem 'bitpay-sdk', :require => 'bitpay_sdk'
+```ruby
+gem 'bitpay-sdk', :require => 'bitpay_sdk'
+```
 
 Or directly:
-
-    require 'bitpay_sdk'
+```ruby
+require 'bitpay_sdk'
+```
 
 ## Configuration
 
 The bitpay client creates a cryptographically secure connection to your server by pairing an API code with keys generated by the library. The client can be initialized with pre-existing keys passed in as a pem file, or paired if initialized with a pem file and a tokens hash. Examples can be found in the cucumber step helpers.
 
-## Basic Usage
+## Client Setup
 
 ### Pairing with Bitpay.com
 
-To pair with bitpay.com you need to have an approved merchant account.  
-1. Login to your account  
-2. Navigate to bitpay.com/api-tokens (Dashboard > My Account > API Tokens)  
-3. Create a new token and copy the pairing code.  
+Most calls to the BitPay REST API require that your client is paired with the bitpay.com server.  To pair with bitpay.com you need to have an approved merchant account.
+
+Your client can be paired via the `pos` (point-of-sale) or `merchant` facade (or both).  The `pos` facade allows for invoices to be created.  The `merchant` facade has broader privileges to view all invoices, bills, and ledger entries, as well as to issue refunds.  Consider the level of access required when you pair your client.
+
+_For development or quick deployment purposes, consider the [BitPay Ruby Command-Line Interface](https://github.com/bitpay/ruby-cli) to simplify the deployment process_
+
+### Pairing Programattically
+
+If you are developing a client with built-in pairing capability, you can pair programattically using the `pair_client` method.  This method can be called in two ways:
+
+  * `pair_client()` will perform a client-initiated pairing, and will provide a pairing code that can be entered at https://bitpay.com/dashboard/merchant/api-tokens to assign either `merchant` or `pos` facade.
+  * `pair_client('pairing_code')` will complete a server-initiated pairing, when provided a pre-generated pairing code from https://bitpay.com/dashboard/merchant/api-tokens.  In this case, the `pos` facade will be automatically assigned.
 
-    client = BitPay::Client.new
-    client.pair_pos_client(<pairing_code>)
-    invoice = client.create_invoice (price: <price>, currency: <currency>)
+The example below demonstrates this using a locally generated PEM file using OpenSSL and the irb tool.
+
+```bash
+$ gem install bitpay-sdk
+Successfully installed bitpay-sdk-2.2.0
+1 gem installed
+$ openssl ecparam -genkey -name secp256k1 -noout -out bitpaykey.pem
+$ irb
+2.1.1 :001 > require 'bitpay_sdk'
+ => true 
+2.1.1 :002 > client = BitPay::SDK::Client.new(api_uri: 'https://test.bitpay.com', pem: File.read('bitpaykey.pem'), insecure: true)
+ => #<BitPay::SDK::Client:0x000000019c6d40 @pem="---... @tokens={}> 
+2.1.1 :003 > client.pair_client()
+ => {"data"=>[{"policies"=>[{"policy"=>"id", "method"=>"inactive", "params"=>["Tf49SFeiUAtytFEW2EUqZgWj32nP51PK73M"]}], "token"=>"BKQyVdaGQZAArdkkSuvtZN5gcN2355c8vXLj5eFPkfuK", "dateCreated"=>1422474475162, "pairingExpiration"=>1422560875162, "pairingCode"=>"Vy76yTh"}]} 
+```
+
+As described above, using the value from the `pairingCode` element, visit https://test.bitpay.com/api-tokens and search to register for the appropriate facade
+
+## General Usage
+
+### Initialize the client
+
+```ruby
+client = BitPay::SDK::Client.new(pem: File.read('bitpaykey.pem')
+```
+    
+Optional parameters:
+ * `api_uri` - specify a different api endpoint (e.g. 'https://test.bitpay.com').  Ensure no trailing slash.
+ * `tokens` - pass a stored hash of bitpay API tokens
+ * `user-agent` - specify a custom user-agent value
+ * `debug: true` - enable HTTP request logging to $stdout
+ * `insecure: true` - disable HTTPs certificate validation (for local test environments)
+
+### Create a new bitcoin invoice
+
+```ruby
+invoice = client.create_invoice (price: <price>, currency: <currency>)
+```
 
 With invoice creation, `price` and `currency` are the only required fields. If you are sending a customer from your website to make a purchase, setting `redirectURL` will redirect the customer to your website when the invoice is paid.
 
 Response will be a hash with information on your newly created invoice. Send your customer to the `url` to complete payment:
 
-    {
-      "id"             => "DGrAEmbsXe9bavBPMJ8kuk", 
-      "url"            => "https://bitpay.com/invoice?id=DGrAEmbsXe9bavBPMJ8kuk",
-      "status"         => "new",
-      "btcPrice"       => "0.0495",
-      "price"          => 10,
-      "currency"       => "USD",
-      "invoiceTime"    => 1383265343674,
-      "expirationTime" => 1383266243674,
-      "currentTime"    => 1383265957613
-    }
+```javascript
+{
+  "url": "https://bitpay.com/invoice?id=NKaqMuZWy3BAcP77RdkEEv",
+  "paymentUrls": {
+    "BIP21": "bitcoin:mvYRECDxKPaPHnjNz9ZxiTpbx29xYNoRy4?amount=0.3745",
+    "BIP72": "bitcoin:mvYRECDxKPaPHnjNz9ZxiTpbx29xYNoRy4?amount=0.3745&r=https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv",
+    "BIP72b": "bitcoin:?r=https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv",
+    "BIP73": "https://bitpay.com/i/NKaqMuZWy3BAcP77RdkEEv"
+  },
+  "status": "new",
+  "btcPrice": "0.3745",
+  "btcDue": "0.3745",
+  "price": 148,
+  "currency": "USD",
+  "exRates": {
+    "USD": 395.20000000000005
+  },
+  "invoiceTime": 1415987168612,
+  "expirationTime": 1415988068612,
+  "currentTime": 1415987168629,
+  "guid": "438e8237-fff1-483c-81b4-dc7dba28922a",
+  "id": "NKaqMuZWy3BAcP77RdkEEv",
+  "transactions": [
+
+  ],
+  "btcPaid": "0.0000",
+  "rate": 395.2,
+  "exceptionStatus": false,
+  "token": "9kZgUXFb5AC6qMuLaMpP9WopbM8X2UjMhkphKKdaprRbSKgUJNE6JNTX8bGsmgxKKv",
+  "buyer": {
+  }
+}
+```
 
 There are many options available when creating invoices, which are listed in the [BitPay API documentation](https://bitpay.com/bitcoin-payment-gateway-api).
 
-To get updated information on this invoice, make a get call with the id returned:
+### Get invoice status
 
-    invoice = client.get_public_invoice(id: 'DGrAEmbsXe9bavBPMJ8kuk')
+The ruby library provides two methods for fetching an existing invoice:
+
+```ruby
+# For authorized clients with a 'merchant' token
+client.get_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
+    
+# For non-authenticated clients (public facade)
+# Returns the public subset of invoice fields
+client.get_public_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
+```
+
+### Create a refund request
+
+Clients with a `merchant` token can initiate a refund request for a paid invoice:
+
+```ruby
+client.refund_invoice(id: '6pbV13VBZfGFJ8BBmXmLZ8', params: {amount: 10, currency: 'USD'})
+```
+    
+Refund rules:
+
+ * Invoices cannot be refunded prior to 6 blockchain confirmations
+ * Invoices without `["flags"]["refundable"] == true` must specify a `bitcoinAddress` param (one was not provided as part of the transaction)
+ * Invoices that are paid in full must specify an `amount` and `currency` param to indicate the amount to be refunded
+
+### View Refund Requests
+
+The ruby library provides two methods for viewing refund requests.  Both require a `merchant` token.
+
+```ruby
+# To get an array of all refunds against a specific invoice
+client.get_all_refunds_for_invoice(id: 'PvVhgBfA7wKPWhuVC24rJo')
+    
+# To get a specific refund for a specific invoice
+client.get_refund(id: 'JB49z2MsDH7FunczeyDS8j', request_id: '4evCrXq4EDXk4oqDXdWQhX')
+```
+
+### Make a HTTP request directly against the REST API
+
+For API tasks which lack a dedicated library method, BitPay provides a method that will automatically apply the proper cryptographic parameters to a request.
+
+```ruby
+client.send_request("GET", "/invoices/JB49z2MsDH7FunczeyDS8j", facade: 'merchant')
+```
+    
+Usage:
+ * Specify HTTP verb and REST endpoint
+ * Specifying a `facade` will fetch and apply the corresponding `token`
+ * Alternatively provide a `token` explicitly
+ * For `POST` requests, the `params` hash will be included as the message body
 
 ## Testnet Usage
 
 During development and testing, take advantage of the [Bitcoin TestNet](https://en.bitcoin.it/wiki/Testnet) by passing a custom `api_uri` option on initialization:
 
-    BitPay::Client.new(api_uri: "https://test.bitpay.com/api")
+```ruby
+BitPay::SDK::Client.new({api_uri: "https://test.bitpay.com/api"})
+```
+
+Note that in order to pair with testnet, you will need a pairing code from test.bitpay.com and will need to use the bitpay client with the --test option.
 
 ## API Documentation
 
@@ -67,10 +192,12 @@ API Documentation is available on the [BitPay site](https://bitpay.com/api).
 In order to run the tests, you must have phantomjs installed and on your PATH.
 
 The tests require that environment variables be set for the bitpay server, user name, and password. First run:
-    
-    $ source ./spec/set_constants.sh https://test.bitpay.com <yourusername> <yourpassword>
-    $ bundle install
-    $ bundle exec rake
+
+```bash    
+$ source ./spec/set_constants.sh https://test.bitpay.com <yourusername> <yourpassword>
+$ bundle install
+$ bundle exec rake
+```
 
 Tests are likely to run up against rate limiters on test.bitpay.com if used too frequently. Rake tasks which interact directly with BitPay will not run for the general public.
 

data/Rakefile

@@ -10,12 +10,19 @@ require_relative 'config/capybara.rb'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+#task :default => :spec
+task :default => :default_tasks
 
 Cucumber::Rake::Task.new(:features) do |t|
     t.cucumber_opts = "features --format pretty"
 end
 
+desc "Run BitPay tests"
+task :default_tasks do
+  Rake::Task["spec"].invoke
+  Rake::Task["features"].invoke
+end
+
 desc "Bitpay Tasks"
 namespace :bitpay do
 

data/bitpay-sdk.gemspec

@@ -17,19 +17,19 @@ Gem::Specification.new do |s|
   s.bindir        = 'bin'
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
 
-  s.add_dependency 'json',      '~> 1.8.1'
-  s.add_dependency 'rack',      '~> 1.5.2'
-  s.add_dependency 'ecdsa',     '~> 1.2.0'
+  s.add_dependency 'json',      '1.8.1'
+  s.add_dependency 'rack',      '1.5.2'
+  s.add_dependency 'ecdsa',     '1.2.0'
 
-  s.add_development_dependency 'rake', '~> 10.3.2'
-  s.add_development_dependency 'webmock', '~> 1.18.0'
-  s.add_development_dependency 'pry', '~> 0.10.1'
-  s.add_development_dependency 'pry-byebug', '~> 2.0.0'
-  s.add_development_dependency 'pry-rescue', '~> 1.4.1'
-  s.add_development_dependency 'capybara', '~> 2.4.3'
-  s.add_development_dependency 'cucumber', '~> 1.3.17'
-  s.add_development_dependency 'poltergeist', '~> 1.5.1'
-  s.add_development_dependency 'airborne', '~> 0.0.20'
-  s.add_development_dependency 'rspec', '~> 3.1.0'
-  s.add_development_dependency 'mongo', '~> 1.11.1'
+  s.add_development_dependency 'rake', '10.3.2'
+  s.add_development_dependency 'webmock', '1.18.0'
+  s.add_development_dependency 'pry', '0.10.1'
+  s.add_development_dependency 'pry-byebug', '2.0.0'
+  s.add_development_dependency 'pry-rescue', '1.4.1'
+  s.add_development_dependency 'capybara', '2.4.3'
+  s.add_development_dependency 'cucumber', '1.3.17'
+  s.add_development_dependency 'poltergeist', '1.5.1'
+  s.add_development_dependency 'airborne', '0.0.20'
+  s.add_development_dependency 'rspec', '3.1.0'
+  s.add_development_dependency 'mongo', '1.11.1'
 end

data/config/capybara.rb

@@ -2,5 +2,5 @@ Capybara.javascript_driver = :poltergeist
 Capybara.default_driver = :poltergeist
 Capybara.default_wait_time = 5
 Capybara.register_driver :poltergeist do |app|
-  Capybara::Poltergeist::Driver.new(app, js_errors: false, phantomjs_options: ['--ignore-ssl-errors=yes', '--ssl-protocol=TLSv1', '--web-security=false'] )
+	Capybara::Poltergeist::Driver.new(app, timeout: 60, js_errors: false, phantomjs_options: ['--ignore-ssl-errors=yes', '--ssl-protocol=TLSv1', '--web-security=false'])
 end

data/config/constants.rb

@@ -1,3 +1,19 @@
+## Verifies test variables have been set correctly 
+#
+#  Use 'set_constants.sh' to pre-configure test variables
+#  e.g.
+#    source ./spec/set_constants.sh https://test.bitpay.com testuser@gmail.com mypassword
+#
+
 ROOT_ADDRESS = ENV['RCROOTADDRESS']
 TEST_USER = ENV['RCTESTUSER']
 TEST_PASS = ENV['RCTESTPASSWORD']
+DASHBOARD_URL = "#{ROOT_ADDRESS}/dashboard/merchant/home"
+
+unless
+	ROOT_ADDRESS &&
+	TEST_USER &&
+	TEST_PASS
+then
+	raise "Missing configuration options - see constants.rb"
+end

data/features/creating_invoices.feature

@@ -11,16 +11,16 @@ Feature: creating an invoice
     Then they should recieve an invoice in response for <price> <currency>
   Examples:
     | price    | currency |
-    | "500.23" | "USD"    |
-    | "300.21" | "EUR"    |
+    | "5.23" | "USD"    |
+    | "10.21" | "EUR"    |
 
   Scenario Outline: The invoice contains illegal characters
     When the user creates an invoice for <price> <currency>
     Then they will receive a BitPay::ArgumentError matching <message>
   Examples:
     | price    | currency  | message                              |
-    | "50,023" | "USD"     | "Price must be formatted as a float" |
-    | "300.21" | "EaUR"    | "Currency is invalid."               |
+    | "5,023" | "USD"     | "Price must be formatted as a float" |
+    | "3.21" | "EaUR"    | "Currency is invalid."               |
     | ""       | "USD"     | "Price must be formatted as a float" |
     | "Ten"    | "USD"     | "Price must be formatted as a float" |
-    | "100"    | ""        | "Currency is invalid."               |
+    | "10"    | ""        | "Currency is invalid."               |

data/features/pairing.feature

@@ -6,13 +6,16 @@ Feature: pairing with bitpay
   Scenario: the client has a correct pairing code
     Given the user pairs with BitPay with a valid pairing code
     Then the user is paired with BitPay
+    
+  Scenario: the client initiates pairing
+    Given the user requests a client-side pairing
+    Then they will receive a claim code
 
   Scenario Outline: the client has a bad pairing code
     Given the user fails to pair with a semantically <valid> code <code>
     Then they will receive a <error> matching <message>
   Examples:
       | valid   | code       | error                 | message                       |
-      | valid   | "a1b2c3d"  | BitPay::BitPayError   | "500: Unable to create token" |
       | invalid | "a1b2c3d4" | BitPay::ArgumentError | "pairing code is not legal"   |
 
   Scenario: the client has a bad port configuration to a closed port

data/features/step_definitions/invoice_steps.rb

@@ -1,9 +1,9 @@
 When(/^the user (?:tries to |)creates? an invoice (?:for|without) "(.*?)" (?:or |and |)"(.*?)"$/) do |price, currency|
   begin
     @response = @client.create_invoice(price: price, currency: currency)
-  rescue => error
-    @error = error
-  end
+   rescue => error
+     @error = error
+   end
 end
 
 Then(/^they should recieve an invoice in response for "(.*?)" "(.*?)"$/) do |price, currency|
@@ -15,8 +15,8 @@ Given(/^there is an invalid token$/) do
 end
 
 Given(/^that a user knows an invoice id$/) do
-  client = new_paired_client
-  @id = (client.create_invoice(price: 100, currency: "USD" ))['id']
+  client = new_client_from_stored_values
+  @id = (client.create_invoice(price: 3, currency: "USD" ))['id']
 end
 
 Then(/^they can retrieve that invoice$/) do

data/features/step_definitions/keygen_steps.rb

@@ -5,6 +5,7 @@ When(/^the user pairs with BitPay(?: with a valid pairing code|)$/) do
   claim_code = get_claim_code_from_server
   pem = BitPay::KeyUtils.generate_pem
   @client = BitPay::SDK::Client.new(api_uri: ROOT_ADDRESS, pem: pem, insecure: true)
+  sleep 1 # rate limit compliance
   @token = @client.pair_pos_client(claim_code)
 end
 
@@ -13,6 +14,7 @@ When(/^the fails to pair with BitPay because of an incorrect port$/) do
   address = ROOT_ADDRESS.split(':').slice(0,2).join(':') + ":999"
   client = BitPay::SDK::Client.new(api_uri: address, pem: pem, insecure: true)
   begin
+    sleep 1 # rate limit compliance
     client.pair_pos_client("1ab2c34")
     raise "pairing unexpectedly worked"
   rescue => error
@@ -26,9 +28,10 @@ Given(/^the user is authenticated with BitPay$/) do
 end
 
 Given(/^the user is paired with BitPay$/) do
-  raise "Client is not paired" unless @client.verify_token
+  raise "Client is not paired" unless @client.verify_tokens
 end
 
+
 Given(/^the user has a bad pairing_code "(.*?)"$/) do |arg1|
     # This is a no-op, pairing codes are transient and never actually saved
 end
@@ -37,6 +40,7 @@ Then(/^the user fails to pair with a semantically (?:in|)valid code "(.*?)"$/) d
   pem = BitPay::KeyUtils.generate_pem
   client = BitPay::SDK::Client.new(api_uri: ROOT_ADDRESS, pem: pem, insecure: true)
   begin
+    sleep 1 # rate limit compliance
     client.pair_pos_client(code)
     raise "pairing unexpectedly worked"
   rescue => error
@@ -49,3 +53,13 @@ Then(/^they will receive an? (.*?) matching "(.*?)"$/) do |error_class, error_me
   raise "Error: #{@error.class}, message: #{@error.message}" unless Object.const_get(error_class) == @error.class && @error.message.include?(error_message)
 end
 
+Given(/^the user requests a client\-side pairing$/) do
+  sleep 1
+  pem = BitPay::KeyUtils.generate_pem
+  client = BitPay::SDK::Client.new(api_uri: ROOT_ADDRESS, pem: pem, insecure: true)
+  @response = client.pair_client({})
+end
+
+Then(/^they will receive a claim code$/) do
+  expect(@response["data"].first["pairingCode"] ).not_to be_empty
+end