quaderno 1.15.2 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: d88e283d2865f257d6d5c3ce29eb4d9fe2f0e749
-  data.tar.gz: 11cb11199deb03cd17b9178eccc15bf3dd5bb432
+SHA256:
+  metadata.gz: 18ba0623ca695fdd9f95f1bb922e7002f6482224aa8b793b307bbe233327b0d9
+  data.tar.gz: 0d3719afdbbfc2739a64513d451444f7bfd268fe9a521e6522f24d160acf7612
 SHA512:
-  metadata.gz: 30ea0846d2cebbd5e7e89a1627f5d6b7ad09306653ed002e35e1a65aeb1cda704011e13c9fd20d68206e0e6c5bb4213b217442fa6b9e4123705e207e74af63c1
-  data.tar.gz: 24baa78f3ea03595912cce861676edd2f139733d6ac4835d266baf23dc8eae6fe287c8045a3116c7fdb0e9c43dfd34020d4c31f5389b9b4af89231e3ca152eb3
+  metadata.gz: 2ce0a701562afa7626f8bc0f6ee19a72f2a36360c65a2aff42732bb6aa2fdfd71fc3f22039c4d910a33ccd01f5df528fe5453ebd6d50d05ae71097b1a0986373
+  data.tar.gz: 38aeb9bd57999f419ead00c46a4f2382de663b8c18c935dc13c9ea9f5b43d4dfcc80b3cb822d55f7d2c884ac6fe0ad14b679b6e7da43d2bd01e329a310da437f

data/README.md

@@ -2,7 +2,7 @@
 
 Quaderno-ruby is a ruby wrapper for [Quaderno API] (https://github.com/quaderno/quaderno-api).
 
-Current version is 1.15.2 See the changelog [here](https://github.com/quaderno/quaderno-ruby/blob/master/changelog.md)
+Current version is 2.0.1 See the changelog [here](https://github.com/quaderno/quaderno-ruby/blob/master/changelog.md)
 
 ## Installation & Configuration
 
@@ -29,8 +29,8 @@ To configure just add this to your initializers
 You can get your account subdomain by grabbing it from your account url or by calling the authorization method with your personal api token.
 
 ```ruby
-  Quaderno::Base.authorization 'my_authenticate_token', environment
-  # => {"identity"=>{"id"=>737000, "name"=>"Walter White", "email"=>"cooking@br.bd", "href"=>"https://my_subdomain.quadernoapp.com/api/"}}
+  response = Quaderno::Base.authorization 'my_authenticate_token', environment #=> Quaderno::Base
+  response.identity # => {"id"=>737000, "name"=>"Walter White", "email"=>"cooking@br.bd", "href"=>"https://my_subdomain.quadernoapp.com/api/"}
 ```
 
 `environment` is an optional argument. By passing `:sandbox`, you will retrieve your credentials for the sandbox environment and not for production.
@@ -41,19 +41,48 @@ This will return a hash with the information about your api url, which includes
  You can ping the service in order to check if it is up with:
 
 ```ruby
-  Quaderno::Base.ping #=> Boolean
+  response = Quaderno::Base.ping #=> Quaderno::Base
+
+  response.status #=> Boolean
 ```
 
-This will return true if the service is up or false if it is not.
+This will return `status: true` if the service is up or `status: false` if it is not.
 
 ## Check the rate limit
 
 ```ruby
-  Quaderno::Base.rate_limit_info #=>  {:reset=>4, :remaining=>0}
+  response = Quaderno::Base.ping #=> Quaderno::Base
+  response.rate_limit_info #=>  { :reset=> 4, :remaining=> 0 }
+
 ```
 
 This will return a hash with information about the seconds until the rate limit reset and your remaining requests per minute ([check the API documentation for more information](https://github.com/quaderno/quaderno-api#rate-limiting)).
 
+You can also check the rate limit for each request by checking the `rate_limit_info` method on the response:
+
+```ruby
+
+  invoices = Quaderno::Invoice.all #=> Quaderno::Collection
+  invoices.rate_limit_info #=> {:reset=> 5, :remaning=>6}
+
+  invoice = Quaderno::Invoice.find INVOICE_ID #=> Quaderno::Invoice
+  invoice.rate_limit_info #=> {:reset=>4, :remaining=>5}
+
+  result = invoice.deliver #=> Quaderno::Base
+  result.rate_limit_info #=> {:reset=>3, :remaining=>4}
+
+  begin
+    deleted_invoice = Quaderno::Invoice.delete(ANOTHER_INVOICE_ID) #=> Quaderno::Invoice
+  rescue Quaderno::Exceptions::InvalidSubdomainOrToken => e
+    # If the exception is triggered you can check the rate limit on the raised exception
+    e.rate_limit_info #=> {:reset=>2, :remaining=>3}
+  end
+
+  deleted_invoice.rate_limit_info #=> {:reset=>2, :remaining=>3}
+
+  # etc.
+```
+
 ## Reading the values
 
 Quaderno-ruby parses all the json responses in human readable data, so you can access each value just like this:
@@ -69,11 +98,10 @@ Quaderno-ruby parses all the json responses in human readable data, so you can a
 
 ### Getting contacts
 ```ruby
- Quaderno::Contact.all() #=> Array
- Quaderno::Contact.all(page: 1) #=> Array
+ Quaderno::Contact.all #=> Array
 ```
 
- will return an array with all your contacts on the first page. You can also pass query strings using the attribute :q in order to filter the results by contact name. For example:
+ will return an array with all your contacts. You can also pass query strings using the attribute :q in order to filter the results by contact name. For example:
 
 ```ruby
  Quaderno::Contact.all(q: 'John Doe') #=> Array
@@ -111,16 +139,16 @@ will update the specified contact with the data of the hash passed as second par
 
 ### Deleting a contact
 ```ruby
-  Quaderno::Contact.delete(id) #=> Boolean
+  Quaderno::Contact.delete(id) #=> Quaderno::Contact
 ```
 
-will delete the contact with the id passed as parameter.
+will delete the contact with the id passed as parameter. If the deletion was successful, an instance of `Quaderno::Contact` with the `deleted` attribute set to `true` will be returned.
 
 ## Managing items
 
 ### Getting items
 ```ruby
-  Quaderno::Item.all() #=> Array
+  Quaderno::Item.all #=> Array
 ```
 
 will return an array with all your items.
@@ -148,10 +176,10 @@ will update the specified item with the data of the hash passed as second parame
 
 ### Deleting an item
 ```ruby
-  Quaderno::Item.delete(id) #=> Boolean
+  Quaderno::Item.delete(id) #=> Quaderno::Item
 ```
 
-will delete the item with the id passed as parameter.
+will delete the item with the id passed as parameter.  If the deletion was successful, an instance of `Quaderno::Item` with the `deleted` attribute set to `true` will be returned.
 
 
 ## Managing invoices
@@ -159,10 +187,9 @@ will delete the item with the id passed as parameter.
 ### Getting invoices
 ```ruby
   Quaderno::Invoice.all #=> Array
-  Quaderno::Invoice.all(page: 1) #=> Array
 ```
 
- will return an array with all your invoices on the first page. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
+ will return an array with all your invoices. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
 
 ### Finding an invoice
 ```ruby
@@ -196,10 +223,10 @@ will update the specified invoice with the data of the hash passed as second par
 ### Deleting an invoice
 
 ```ruby
-  Quaderno::Invoice.delete(id) #=> Boolean
+  Quaderno::Invoice.delete(id) #=> Quaderno::Invoice
 ```
 
-will delete the invoice with the id passed as parameter.
+will delete the invoice with the id passed as parameter. If the deletion was successful, an instance of `Quaderno::Item` with the `deleted` attribute set to `true` will be returned.
 
 
 ###Adding or removing a payment
@@ -219,74 +246,25 @@ In order to  remove a payment you will need the Invoice instance you want to upd
   invoice.remove_payment(payment_id) #=> Boolean
 ```
 
-###Delivering the invoice
+### Delivering the invoice
 
   In order to deliver the invoice to the default recipient you will need the invoice you want to send.
 
 ```ruby
   invoice = Quaderno::Invoice.find(invoice_id)
-  invoice.deliver
-```
-
-## Managing receipts
-
-### Getting receipts
-```ruby
-  Quaderno::Receipt.all #=> Array
-  Quaderno::Receipt.all(page: 1) #=> Array
-```
-
- will return an array with all your receipts on the first page. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
-
-### Finding a receipt
-```ruby
-  Quaderno::Receipt.find(id) #=> Quaderno::Receipt
-```
-
-will return the receipt with the id passed as parameter.
-
-### Creating a new receipt
-
-```ruby
-  Quaderno::Receipt.create(params) #=> Quaderno::Receipt
-```
-
-will create an receipt using the information of the hash passed as parameter.
-
-### Updating an existing receipt
-```ruby
-  Quaderno::Receipt.update(id, params) #=> Quaderno::Receipt
-```
-
-will update the specified receipt with the data of the hash passed as second parameter.
-
-### Deleting an receipt
-
-```ruby
-  Quaderno::Receipt.delete(id) #=> Boolean
-```
-
-will delete the receipt with the id passed as parameter.
-
-###Delivering the receipt
+  result = invoice.deliver #=> Quaderno::Base
 
-  In order to deliver the receipt to the default recipient you will need the receipt you want to send.
-
-```ruby
-  receipt = Quaderno::Receipt.find(receipt_id)
-  receipt.deliver
+  result.success #=> Boolean
 ```
 
-
 ## Managing credits
 
 ### Getting credits
 ```ruby
   Quaderno::Credit.all #=> Array
-  Quaderno::Credit.all(page: 1) #=> Array
 ```
 
- will return an array with all your credit notes on the first page. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
+ will return an array with all your credit notes. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
 
 ### Finding a credit
 ```ruby
@@ -304,10 +282,10 @@ will return the credit note with the transaction id passed as parameter.
 ### Creating a new credit
 
 ```ruby
-  Quaderno::Credit.create(params) #=> Quaderno::Credit
+  Quaderno::Credit.create(invoice_id: 42) #=> Quaderno::Credit
 ```
 
-will create a credit using the information of the hash passed as parameter.
+will create a credit from the invoice specified in the parameter.
 
 ### Updating an existing credit
 ```ruby
@@ -319,13 +297,13 @@ will update the specified credit with the data of the hash passed as second para
 ### Deleting a credit
 
 ```ruby
-  Quaderno::Credit.delete(id) #=> Boolean
+  Quaderno::Credit.delete(id) #=> Quaderno::Credit
 ```
 
-will delete the credit with the id passed as parameter.
+will delete the credit with the id passed as parameter. If the deletion was successful, an instance of `Quaderno::Credit` with the `deleted` attribute set to `true` will be returned.
 
 
-###Adding or removing a payment
+### Adding or removing a payment
  In order to  add a payment you will need the Credit instance you want to update.
 
 ```ruby
@@ -339,16 +317,20 @@ In order to  remove a payment you will need the Credit instance you want to upda
 
 ```ruby
   credit = Quaderno::Credit.find(credit_id)
-  credit.remove_payment(payment_id) #=> Boolean
+  credit.remove_payment(payment_id) #=> Quaderno::Payment
 ```
 
-###Delivering the credit
+If the deletion was successful, an instance of `Quaderno::Payment` with the `deleted` attribute set to `true` will be returned.
+
+### Delivering the credit
 
   In order to deliver the credit to the default recipient you will need the credit you want to send.
 
 ```ruby
   credit = Quaderno::Credit.find(credit_id)
-  credit.deliver
+  result = credit.deliver #=> Quaderno::Base
+
+  result.success #=> Boolean
 ```
 
 
@@ -357,11 +339,10 @@ In order to  remove a payment you will need the Credit instance you want to upda
 
 ### Getting estimates
 ```ruby
-  Quaderno::Estimate.all() #=> Array
-  Quaderno::Estimate.all(page: 1) #=> Array
+  Quaderno::Estimate.all #=> Array
 ```
 
- will return an array with all your estimates on the first page.
+ will return an array with all your estimates.
 
 ### Finding an estimate
 ```ruby
@@ -388,10 +369,10 @@ will update the specified estimate with the data of the hash passed as second pa
 ### Deleting an estimate
 
 ```ruby
-  Quaderno::Estimate.delete(id) #=> Boolean
+  Quaderno::Estimate.delete(id) #=> Quaderno::Estimate
 ```
 
-will delete the estimate with the id passed as parameter.
+will delete the estimate with the id passed as parameter. If the deletion was successful, an instance of `Quaderno::Contact` with the `deleted` attribute set to `true` will be returned.
 
 
 ###Adding or removing a payment
@@ -411,12 +392,14 @@ In order to  remove a payment you will need the estimate you want to update.
   estimate.remove_payment(payment_id) #=> Boolean
 ```
 
-###Delivering the estimate
+### Delivering the estimate
   In order to deliver the estimate to the default recipient you will need the estimate you want to send.
 
 ```ruby
   estimate = Quaderno::Estimate.find(estimate_id)
-  estimate.deliver
+  result = estimate.deliver #=> Quaderno::Base
+
+  result.success #=> Boolean
 ```
 
 
@@ -424,11 +407,10 @@ In order to  remove a payment you will need the estimate you want to update.
 
 ### Getting expenses
 ```ruby
- Quaderno::Expense.all() #=> Array
- Quaderno::Expense.all(page: 1) #=> Array
+ Quaderno::Expense.all #=> Array
 ```
 
- will return an array with all your expenses on the first page. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date.
+ will return an array with all your expenses. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date.
 
 ### Finding an expense
 ```ruby
@@ -453,10 +435,10 @@ will update the specified expense with the data of the hash passed as second par
 
 ### Deleting an expense
 ```ruby
-  Quaderno::Expense.delete(id) #=> Boolean
+  Quaderno::Expense.delete(id) #=> Quaderno::Expense
 ```
 
-will delete the expense with the id passed as parameter.
+will delete the expense with the id passed as parameter. If the deletion was successful, an instance of `Quaderno::Expense` with the `deleted` attribute set to `true` will be returned.
 
 
 ## Managing recurrings
@@ -464,10 +446,9 @@ will delete the expense with the id passed as parameter.
 ### Getting recurrings
 ```ruby
   Quaderno::Recurring.all #=> Array
-  Quaderno::Recurring.all(page: 1) #=> Array
 ```
 
- will return an array with all your recurring notes on the first page. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
+ will return an array with all your recurring notes. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
 
 ### Finding a recurring
 ```ruby
@@ -494,17 +475,17 @@ will update the specified recurring with the data of the hash passed as second p
 ### Deleting a recurring
 
 ```ruby
-  Quaderno::Recurring.delete(id) #=> Boolean
+  Quaderno::Recurring.delete(id) #=> Quaderno::Recurring
 ```
 
-will delete the recurring with the id passed as parameter.
+will delete the recurring with the id passed as parameter. If the deletion was successful, an instance of `Quaderno::Recurring` with the `deleted` attribute set to `true` will be returned.
 
 
 ## Managing webhooks
 
 ### Getting webhooks
 ```ruby
- Quaderno::Webhook.all() #=> Array
+ Quaderno::Webhook.all #=> Array
 ```
 
  will return an array with all the webhooks you have subscribed.
@@ -532,9 +513,9 @@ will update the specified webhook with the data of the hash passed as second par
 
 ### Deleting a webhook
 ```ruby
-  Quaderno::Webhook.delete(id) #=> Boolean
+  Quaderno::Webhook.delete(id) #=> Quaderno::Webhook
 ```
-will delete the webhook with the id passed as parameter.
+will delete the webhook with the id passed as parameter. If the deletion was successful, an instance of `Quaderno::Webhook` with the `deleted` attribute set to `true` will be returned.
 
 
 ## Taxes
@@ -548,10 +529,12 @@ will calculate the taxes applied for a customer based on the data pased as param
 
 ### Validate VAT numbers
 ```ruby
-country = 'IE'
-vat_number = 'IE6388047V'
+ country = 'IE'
+ vat_number = 'IE6388047V'
 
- Quaderno::Tax.validate_vat_number(country, vat_number) #=> Boolean
+ result = Quaderno::Tax.validate_vat_number(country, vat_number) #=> Quaderno::Tax
+
+ result.valid #=> Boolean or nil
 ```
 
 will validate the vat number for the passed country.
@@ -565,6 +548,43 @@ will validate the vat number for the passed country.
 
 will create an evidence based on the data pased as parameters.
 
+## Checkout Sessions
+
+### Getting checkout sessions
+```ruby
+ Quaderno::CheckoutSession.all #=> Array
+```
+
+ will return an array with all the checkout sessions in your account.
+
+### Finding a checkout session
+```ruby
+ Quaderno::CheckoutSession.find(id) #=> Quaderno::CheckoutSession
+```
+
+will return the checkout session with the id passed as parameter.
+
+### Creating a new checkout session
+```ruby
+ Quaderno::CheckoutSession.create(params) #=> Quaderno::CheckoutSession
+```
+
+will create a checkout session using the information of the hash passed as parameter and return an instance of Quaderno::CheckoutSession with the created checout session.
+
+### Updating an existing checkout session
+```ruby
+ Quaderno::CheckoutSession.update(id, params) #=> Quaderno::CheckoutSession
+```
+
+will update the specified checkout session with the data of the hash passed as second parameter.
+
+### Deleting a checkout session
+```ruby
+  Quaderno::CheckoutSession.delete(id) #=> Quaderno::CheckoutSession
+```
+will delete the checkout session with the id passed as parameter. If the deletion was successful, an instance of `Quaderno::CheckoutSession` with the `deleted` attribute set to `true` will be returned.
+
+
 ## Exceptions
 Quaderno-ruby exceptions raise depending on the type of error:
 
@@ -591,12 +611,27 @@ All those exceptions inherit from `Quaderno::Exceptions::BaseException`.
 Whenever you call the `all` method on one of the classes, the result will be a `Quaderno::Collection`. For example:
 
 ```ruby
-collection = Quaderno::Contact.all(page: 2)
+collection = Quaderno::Contact.all
 
 collection.class #=> Quaderno::Collection
-collection.pagination_info #=> {:current_page=>"1", :total_pages=>"3"}
-collection.current_page #=> "2"
-collection.total_pages #=> "3"
+collection.has_next? #=> true
+collection.next_page #=> another instance of
+```
+
+The `next_page` method is an abstraction for the `created_before` parameter, which you may also use with the `all` method.
+
+```ruby
+collection = Quaderno::Contact.all
+
+Quaderno::Contact.all(created_before: collection.last.id)
+```
+
+You can also use the `limit` parameter to determine how many results to retrieve. Its default is `25`, and Quaderno will cap the limit at `100`.
+
+```ruby
+collection = Quaderno::Contact.all(limit: 50)
+
+collection.length #=> 50
 ```
 
 ### Thread-safe configuration
@@ -653,5 +688,3 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-