fakturoid 0.4.0 → 1.0.0

data/README.md

@@ -1,7 +1,8 @@
 # Fakturoid
 
-The Fakturoid gem is ruby library for API communication with web based invoicing service [www.fakturoid.cz](https://fakturoid.cz).
-Fakturoid [API documentation](https://fakturoid.docs.apiary.io/).
+The Fakturoid gem is Ruby library for API communication with web based invoicing service [www.fakturoid.cz](https://www.fakturoid.cz/).
+
+Fakturoid [API documentation](https://www.fakturoid.cz/api/v3).
 
 [![Gem Version](https://badge.fury.io/rb/fakturoid.svg)](http://badge.fury.io/rb/fakturoid)
 [![Tests](https://github.com/fakturoid/fakturoid-ruby/actions/workflows/tests.yml/badge.svg)](https://github.com/fakturoid/fakturoid-ruby/actions/workflows/tests.yml)
@@ -17,148 +18,260 @@ gem "fakturoid"
 
 And then run:
 
-    $ bundle
+```sh
+bundle
+```
+
+## Gem Versions
+
+| Gem version | Fakturoid API                               | Supported Ruby |
+|-------------|---------------------------------------------|----------------|
+| `1.x`       | [API v3](https://www.fakturoid.cz/api/v3)   | `>=2.7.0`      |
+| `0.x`       | [API v2](https://fakturoid.docs.apiary.io/) | `>=2.7.0`      |
 
 ## Configuration
 
-Fakturoid gem is configured within config block placed in `config/initializers/fakturoid.rb`:
+### Authorization with OAuth 2.0
+
+#### Authorization Code Flow
+
+Authorization using OAuth takes place in several steps. We use data obtained from the developer portal as client ID and
+client secret (Settings → Connect other apps → OAuth 2 for app developers).
+
+First, we offer the user a URL address where he enters his login information. We obtain this using the following method
+(you can place it in an intializer `config/initializers/fakturoid.rb`):
 
 ```ruby
 Fakturoid.configure do |config|
-  config.email = "yourfakturoid@email.com"
-  config.api_key = "fasdff823fdasWRFKW843ladfjklasdf834"
-  config.account = "applecorp" # former subdomain (first part of URL)
-  config.user_agent = "Name of your app (your@email.com)"
+  config.email         = "yourfakturoid@email.com"
+  config.account       = "{fakturoid-account-slug}" # You can also set `account` dynamically later.
+  config.user_agent    = "Name of your app (your@email.com)"
+  config.client_id     = "{fakturoid-client-id}"
+  config.client_secret = "{fakturoid-client-secret}"
+  config.redirect_uri  = "{your-redirect-uri}"
+  config.oauth_flow    = "authorization_code"
 end
 ```
 
-## Usage
+Create a client and let the user come to our OAuth login page:
 
-### Account resource
+```ruby
+client = Fakturoid.client
+
+# To be rendered on a web page. State is optional.
+link_to client.authorization_uri, "Enable Fakturoid Integration"
+link_to client.authorization_uri(state: "abcd1234"), "Enable Fakturoid Integration"
+```
 
-To get information about your account in Fakturoid run following code:
+After entering the login data, the user is redirected to the specified redirect URI and with the code with which we
+obtain his credentials. We process the code as follows:
 
 ```ruby
-response = Fakturoid::Client::Account.current
-response.status_code # returns response http code
-response.body # contains hash with returned body
+client.authorize(code: params[:code])
 ```
 
-Accessing content of returned body:
+Credentials are now established in the object instance and we can send queries to the Fakturoid API.
 
 ```ruby
-response.body["name"] # return name of your company
-response.name # alternative way of getting the name of your company
+pp client.credentials.as_json
 ```
 
-For the list of all returned account fields see the [Account API documentation](https://fakturoid.docs.apiary.io/#reference/account)
+Credentials can also be set manually (eg. loaded from a database):
 
-### User resource
+```ruby
+client.credentials = {
+  access_token: "1db22484a6d6256e7942158d216157d075ab6e7b583bd16416181ca6c4ac180167acd8d599bd123d", # Example
+  refresh_token: "5682a4bc6254d85934a03931ed5e235e0f81bca64aef054fa0049d8c953eab919ba67bd8ceb532d7",
+  expires_at: "2024-03-01T12:42:40+01:00", # This also accepts `Time` or `DateTime` object.
+  token_type: "Bearer"
+}
+```
 
-For the information about current user use following code:
+Don't forget to update your credentials after an access token refresh:
 
 ```ruby
-response = Fakturoid::Client::User.current
+client.credentials_updated_callback do |credentials|
+  # Store new credentials into database.
+  pp client.credentials.as_json
+end
 ```
 
-For all the users which belongs to current account:
+You may need to set account slug dynamically:
 
 ```ruby
-response = Fakturoid::Client::User.all
+client.account = client.users.current.body["accounts"].first["slug"]
 ```
 
-If you want to get information about one user which belongs to account use:
+And if you need to create a separate client for a different account:
 
 ```ruby
-response = Fakturoid::Client::User.find(user_id)
+client = Fakturoid::Client.new(account: "{another-fakturoid-account-slug}")
 ```
 
-For the list of all returned user fields see the [Users API documentation](https://fakturoid.docs.apiary.io/#reference/users)
+Revoke access altogether (works in both flows):
 
-### Number Format resource
+```ruby
+client.revoke_access
+```
 
-For the list of invoice number formats which belong to the current account:
+#### Client Credentials Flow
 
 ```ruby
-response = Fakturoid::Client::NumberFormat.invoices
+Fakturoid.configure do |config|
+  config.email         = "yourfakturoid@email.com"
+  config.account       = "{fakturoid-account-slug}"
+  config.user_agent    = "Name of your app (your@email.com)"
+  config.client_id     = "{fakturoid-client-id}"
+  config.client_secret = "{fakturoid-client-secret}"
+  config.oauth_flow    = "client_credentials"
+end
 ```
 
-For the list of all returned user fields see the [Number formats API documentation](https://fakturoid.docs.apiary.io/#reference/number-formats)
+Credentials can be set and stored the same way as above just without a refresh token.
 
-### Subject resource
+## Usage
 
-To get all subjects run (Subjects are paginated by 20 per page):
+Almost all resources that return a list of things are paginated by 40 per page. You can specify the page number
+by passing a `page` parameter: `client.some_resource.all(page: 2)`.
+
+### [User Resource](https://www.fakturoid.cz/api/v3/users)
+
+Get current user information along with a list of accounts he/she has access to
+
+```ruby
+response = client.users.current
+response.status_code # Returns response HTTP code.
+response.body # Contains hash with returned body (JSON is parsed automatically).
+```
+
+Accessing content of returned body:
+
+```ruby
+response.body["name"] # Return name of your company.
+response.name # Alternative way of getting the name of your company.
+```
+
+Get a list of all account users:
 
 ```ruby
-response = Fakturoid::Client::Subject.all(page: 2)
+response = client.users.all
 ```
 
-Fulltext search subjects:
+### [Account Resource](https://www.fakturoid.cz/api/v3/account)
+
+Get Fakturoid account information:
 
 ```ruby
-response = Fakturoid::Client::Subject.search("Client name")
+response = client.account.current
 ```
 
-To find one subject use:
+### [Bank Account Resource](https://www.fakturoid.cz/api/v3/bank-accounts)
+
+Get a list of bank accounts for current account:
 
 ```ruby
-response = Fakturoid::Client::Subject.find(subject_id)
+response = client.bank_accounts.all
 ```
 
-You can create new subject with:
+### [Number Format Resource](https://www.fakturoid.cz/api/v3/number-formats)
+
+Get a list of invoice number formats for current account:
 
 ```ruby
-response = Fakturoid::Client::Subject.create(name: "New client")
+response = client.number_formats.invoices
 ```
 
-To update subject use following code:
+### [Subject Resource](https://www.fakturoid.cz/api/v3/subjects)
+
+Get a list of subjects:
 
 ```ruby
-response = Fakturoid::Client::Subject.update(subject_id, name: "Updated client")
+response = client.subjects.all(page: 2)
 ```
 
-Delete subject:
+Fulltext search:
 
 ```ruby
-Fakturoid::Client::Subject.delete subject_id
+response = client.subjects.search(query: "Client name")
 ```
 
-For the list of all subject fields and options see the [Subjects API documentation](https://fakturoid.docs.apiary.io/#reference/subjects)
+Get a specific subject:
 
-### Invoice resource
+```ruby
+response = client.subjects.find(subject_id)
+```
 
-To get all invoices run (Invoices are paginated by 20 per page):
+Create a new subject:
 
 ```ruby
-response = Fakturoid::Client::Invoice.all(page: 2)
+response = client.subjects.create(name: "New client")
 ```
 
-Fulltext search invoices:
+Update a subject:
 
 ```ruby
-response = Fakturoid::Client::Invoice.search("Client name")
+response = client.subjects.update(subject_id, name: "Updated client")
 ```
 
-To find one invoice use:
+Delete a subject:
 
 ```ruby
-response = Fakturoid::Client::Invoice.find(invoice_id)
+client.subjects.delete(subject_id)
 ```
 
-To download invoice in PDF format you can use following code:
+### [Invoice Resource](https://www.fakturoid.cz/api/v3/invoices)
+
+Get a list of invoices:
 
 ```ruby
-response = Fakturoid::Client::Invoice.download_pdf(invoice_id)
+response = client.invoices.all
+```
+
+Fulltext search:
+
+```ruby
+response = client.invoices.search(query: "Client name")
+response = client.invoices.search(tags: "Housing")
+response = client.invoices.search(tags: ["Housing", "Rent"])
+response = client.invoices.search(query: "Client name", tags: ["Housing"])
+```
+
+Get invoice details:
+
+```ruby
+response = client.invoices.find(invoice_id)
+```
+
+Download invoice in PDF format:
+
+```ruby
+response = client.invoices.download_pdf(invoice_id)
 
 File.open("/path/to/file.pdf", "wb") do |f|
   f.write(response.body)
 end
 ```
 
-You can create new invoice with:
+Download an attachment:
+
+```ruby
+response = client.invoices.download_attachment(invoice_id, attachment_id)
+
+File.open("/path/to/attachment.pdf", "wb") do |f|
+  f.write(response.body)
+end
+```
+
+Invoice actions (eg. lock invoice, cancel, etc., full list is in the API documentation):
+
+```ruby
+response = client.invoices.fire(invoice_id, "lock")
+```
+
+Create an invoice:
 
 ```ruby
-invoice = {
+data = {
   subject_id: 123,
   lines: [
     {
@@ -170,50 +283,447 @@ invoice = {
     }
   ]
 }
-response = Fakturoid::Client::Invoice.create(invoice)
+response = client.invoices.create(data)
+```
+
+Update an invoice:
+
+```ruby
+response = client.invoices.update(invoice_id, number: "2015-0015")
 ```
 
-Invoice actions (eg. pay invoice):
+Delete an invoice:
+
+```ruby
+response = client.invoices.delete(invoice_id)
+```
+
+### [Invoice Payment Resource](https://www.fakturoid.cz/api/v3/invoice-payments)
+
+Create an invoice payment:
 
 ```ruby
-response = Fakturoid::Client::Invoice.fire(invoice_id, "pay")
+response = client.invoice_payments.create(invoice_id, paid_on: Date.today)
+response = client.invoice_payments.create(invoice_id, amount: "500")
+````
+
+Create a tax document for a payment:
+
+```ruby
+response = client.invoice_payments.create_tax_document(invoice_id, payment_id)
+tax_document_response = client.invoices.find(response.tax_document_id)
+````
+
+Delete a payment:
+
+```ruby
+response = client.invoice_payments.delete(invoice_id, payment_id)
 ```
 
-Send invoice with customized message (for more information see [the API Documentation](https://fakturoid.docs.apiary.io/#reference/messages)):
+### [Invoice Message Resource](https://www.fakturoid.cz/api/v3/invoice-messages)
+
+Send a message to the client (you can use more variables in the `message`, full list is in the API documentation):
 
 ```ruby
-message = {
+data = {
   email: "testemail@testemail.cz",
   email_copy: "some@emailcopy.cz",
   subject: "I have an invoice for you",
   message: "Hi,\n\nyou can find invoice no. #no# on the following page #link#\n\nHave a nice day"
 }
 
-response = Fakturoid::Client::Invoice.deliver_message(181, message)
-response.status_code # => 201
+response = client.invoice_messages.create(invoice_id, data)
 ```
 
-To update invoice use following code:
+### [Expense Resource](https://www.fakturoid.cz/api/v3/expenses)
+
+Get a list of expenses:
 
 ```ruby
-response = Fakturoid::Client::Invoice.update(invoice_id, number: "2015-0015")
+response = client.expenses.all
 ```
 
-Delete invoice:
+Fulltext search:
 
 ```ruby
-response = Fakturoid::Client::Invoice.delete(invoice_id)
+response = client.expenses.search(query: "Supplier name")
+response = client.expenses.search(tags: "Housing")
+response = client.expenses.search(tags: ["Housing", "Rent"])
+response = client.expenses.search(query: "Supplier name", tags: ["Housing"])
 ```
 
-For the list of all invoice fields and options see the [Invoices API documentation](https://fakturoid.docs.apiary.io/#reference/invoices)
+Get expense details:
 
-## Handling error responses
+```ruby
+response = client.expenses.find(expense_id)
+```
 
-The Fakturoid gem raises exceptions if error response is returned from the servers. All exceptions contains following attributes:
+Download an attachment:
 
-  - `message` - Error description
-  - `response_code` - http code of error (only number)
-  - `response_body` - response body parsed in the hash
+```ruby
+response = client.expenses.download_attachment(expense_id, attachment_id)
+
+File.open("/path/to/attachment.pdf", "wb") do |f|
+  f.write(response.body)
+end
+```
+
+Expense actions (eg. lock expense etc., full list is in the API documentation):
+
+```ruby
+response = client.expenses.fire(expense_id, "lock")
+```
+
+Create an expense:
+
+```ruby
+data = {
+  subject_id: 123,
+  lines: [
+    {
+      quantity: 5,
+      unit_name: "kg",
+      name: "Sand",
+      unit_price: "100",
+      vat_rate: 21
+    }
+  ]
+}
+response = client.expenses.create(data)
+```
+
+Update an expense:
+
+```ruby
+response = client.expenses.update(expense_id, number: "N20240201")
+```
+
+Delete an expense:
+
+```ruby
+response = client.expenses.delete(expense_id)
+```
+
+### [Expense Payment Resource](https://www.fakturoid.cz/api/v3/expense-payments)
+
+Create an expense payment:
+
+```ruby
+response = client.expense_payments.create(expense_id, paid_on: Date.today)
+response = client.expense_payments.create(expense_id, amount: "500")
+````
+
+Delete a payment:
+
+```ruby
+response = client.expense_payments.delete(expense_id, payment_id)
+```
+
+### [Inbox File Resource](https://www.fakturoid.cz/api/v3/inbox-files)
+
+Get a list of inbox files:
+
+```ruby
+response = client.inbox_files.all
+```
+
+Create an inbox file:
+  
+```ruby
+require "base64"
+
+client.inbox_files.create(
+  attachment: "data:application/pdf;base64,#{Base64.urlsafe_encode64(File.read("some-file.pdf"))}",
+  filename: "some-file.pdf", # This is optional and defaults to `attachment.{extension}`.
+  send_to_ocr: true          # Also optional
+)
+```
+
+Send a file to OCR (data extraction service):
+
+```ruby
+client.inbox_files.send_to_ocr(inbox_file_id)
+```
+
+Download a file:
+
+```ruby
+filename = client.inbox_files.find(inbox_file_id).filename
+response = client.inbox_files.download(inbox_file_id)
+
+File.open("/path/to/file.pdf", "wb") do |f|
+  f.write(response.body)
+end
+```
+
+Delete a file:
+
+```ruby
+response = client.inbox_files.delete(inbox_file_id)
+```
+
+### [InventoryItem Resource](https://www.fakturoid.cz/api/v3/inventory-items)
+
+Get a list of inventory items:
+
+```ruby
+response = client.inventory_items.all
+response = client.inventory_items.all(sku: "SKU1234") # Filter by SKU code
+```
+
+Get a list of archived inventory items:
+
+```ruby
+response = client.inventory_items.archived
+```
+
+Get a list of inventory items that are running low on quantity:
+
+```ruby
+response = client.inventory_items.low_quantity
+```
+
+Search inventory items (searches in `name`, `article_number` and `sku`):
+
+```ruby
+response = client.inventory_items.search(query: "Item name")
+```
+
+Get a single inventory item:
+
+```ruby
+response = client.inventory_items.find(inventory_item_id)
+```
+
+Create an inventory item:
+
+```ruby
+data = {
+  name: "Item name",
+  sku: "SKU1234",
+  track_quantity: true,
+  quantity: 100,
+  native_purchase_price: 500,
+  native_retail_price: 1000
+}
+response = client.inventory_items.create(data)
+```
+
+Update an inventory item:
+
+```ruby
+response = client.inventory_items.update(inventory_item_id, name: "Another name")
+```
+
+Delete an inventory item:
+
+```ruby
+response = client.inventory_items.delete(inventory_item_id)
+```
+
+Archive an inventory item:
+
+```ruby
+response = client.inventory_items.archive(inventory_item_id)
+```
+
+Unarchive an inventory item:
+
+```ruby
+response = client.inventory_items.unarchive(inventory_item_id)
+```
+
+### [InventoryMove Resource](https://www.fakturoid.cz/api/v3/inventory-moves)
+
+Get a list of inventory moves across all inventory items:
+
+```ruby
+response = client.inventory_moves.all
+```
+
+Get a list of inventory moves for a single inventory item:
+
+```ruby
+response = client.inventory_moves.all(inventory_item_id: inventory_item_id)
+```
+
+Get a single inventory move:
+
+```ruby
+response = client.inventory_moves.find(inventory_item_id, inventory_move_id)
+```
+
+Create a stock-in inventory move:
+
+```ruby
+response = client.inventory_moves.create(
+  inventory_item_id,
+  direction: "in",
+  moved_on: Date.today,
+  quantity_change: 5,
+  purchase_price: "249.99",
+  purchase_currency: "CZK",
+  private_note: "Bought with discount"
+)
+```
+
+Create a stock-out inventory move:
+
+```ruby
+response = client.inventory_moves.create(
+  inventory_item_id,
+  direction: "out",
+  moved_on: Date.today,
+  quantity_change: "1.5",
+  retail_price: 50,
+  retail_currency: "EUR",
+  native_retail_price: "1250"
+)
+```
+
+Update an inventory move:
+
+```ruby
+data = {
+  private_note: "Text"
+  # Plus other fields if necessary
+}
+response = client.inventory_moves.update(inventory_item_id, inventory_move_id, data)
+```
+
+Delete an inventory move:
+
+```ruby
+response = client.inventory_moves.delete(inventory_item_id, inventory_move_id)
+```
+
+### [Generator Resource](https://www.fakturoid.cz/api/v3/generators)
+
+Get a list of generators:
+
+```ruby
+response = client.generators.all
+```
+
+Get generator details:
+
+```ruby
+response = client.generators.find(generator_id)
+```
+
+Create a generator:
+
+```ruby
+data = {
+  name: "Workshop",
+  subject_id: 123,
+  lines: [
+    {
+      quantity: 5,
+      unit_name: "kg",
+      name: "Sand",
+      unit_price: "100",
+      vat_rate: 21
+    }
+  ]
+}
+response = client.generators.create(data)
+```
+
+Update an generator:
+
+```ruby
+response = client.generators.update(generator_id, name: "Another name")
+```
+
+Delete an generator:
+
+```ruby
+response = client.generators.delete(generator_id)
+```
+
+### [RecurringGenerator Resource](https://www.fakturoid.cz/api/v3/recurring-generators)
+
+Get a list of recurring generators:
+
+```ruby
+response = client.recurring_generators.all
+```
+
+Get recurring generator details:
+
+```ruby
+response = client.recurring_generators.find(recurring_generator_id)
+```
+
+Create a recurring generator:
+
+```ruby
+data = {
+  name: "Workshop",
+  subject_id: subject_id,
+  start_date: Date.today,
+  months_period: 1,
+  lines: [
+    {
+      quantity: 5,
+      unit_name: "kg",
+      name: "Sand",
+      unit_price: "100",
+      vat_rate: 21
+    }
+  ]
+}
+response = client.recurring_generators.create(data)
+```
+
+Update a recurring generator:
+
+```ruby
+response = client.recurring_generators.update(recurring_generator_id, name: "Another name")
+```
+
+Delete a recurring generator:
+
+```ruby
+response = client.recurring_generators.delete(recurring_generator_id)
+```
+### [Event Resource](https://www.fakturoid.cz/api/v3/events)
+
+Get a list of all events:
+
+```ruby
+response = client.events.all
+````
+
+Get a list of document-paid events:
+
+```ruby
+response = client.events.paid
+````
+
+### [Todo Resource](https://www.fakturoid.cz/api/v3/todos)
+
+Get a list of all todos:
+
+```ruby
+response = client.todos.all
+````
+
+Toggle a todo completion:
+
+```ruby
+response = client.todos.toggle_completion(todo_id)
+```
+
+## Handling Errors
+
+The Fakturoid gem raises exceptions if server responds with an error.
+All exceptions except `ConfigurationError` contain following attributes:
+
+- `message`: Error description
+- `response_code`: HTTP code of error (only number)
+- `response_body`: Response body parsed as a hash
 
 <table>
   <thead>
@@ -223,49 +733,29 @@ The Fakturoid gem raises exceptions if error response is returned from the serve
   </thead>
   <tbody>
     <tr>
-      <td>ContentTypeError</td><td>415 Unsupported Media Type</td><td>Wrong content type</td>
-    </tr>
-    <tr>
-      <td>UserAgentError</td><td>400 Bad Request</td><td>Missing `user_agent` configuration</td>
-    </tr>
-    <tr>
-      <td>PaginationError</td><td>400 Bad Request</td><td>Page with given number does not exist</td>
-    </tr>
-    <tr>
-      <td>AuthenticationError</td><td>401 Unauthorized</td><td>Wrong authentication `email` or `api_key` configuration</td>
-    </tr>
-    <tr>
-      <td>BlockedAccountError</td><td>402 Payment Required</td><td>Fakturoid account is blocked</td>
-    </tr>
-    <tr>
-      <td>RateLimitError</td><td>429 Too Many Requests</td><td>Too many request sent during last 5 minutes</td>
-    </tr>
-    <tr>
-      <td>ReadOnlySiteError</td><td>503 Service Unavailable</td><td>Fakturoid is read only</td>
-    </tr>
-    <tr>
-      <td>RecordNotFoundError</td><td>404 Not Found</td><td>Document with given ID does not exists or current account has read only permission and trying to edit something</td>
-    </tr>
-    <tr>
-      <td>InvalidRecordError</td><td>422 Unprocessable Entity</td><td>Invalid data sent to server</td>
-    </tr>
-    <tr>
-      <td>DestroySubjectError</td><td>403 Forbidden</td><td>Subject has invoices or expenses and cannot be deleted</td>
+      <td>ConfigurationError</td><td>N/A</td><td>Important configuration is missing.</td>
     </tr>
     <tr>
-      <td>SubjectLimitError</td><td>403 Forbidden</td><td>Subject quota reached for adding more subjects upgrade to higher plan</td>
+      <td>OauthError</td><td>400 Bad Request</td><td>OAuth request fails.</td>
     </tr>
     <tr>
-      <td>GeneratorLimitError</td><td>403 Forbidden</td><td>Generator quota reached for adding more recurring generators upgrade to higher plan</td>
+      <td>AuthenticationError</td><td>401 Unauthorized</td><td>Authentication fails due to client credentials error or access token expired.</td>
     </tr>
     <tr>
-      <td>UnsupportedFeatureError</td><td>403 Forbidden</td><td>Feature is not supported in your plan to use this feature upgrade to higher plan</td>
+      <td>ClientError</td><td>4XX</td><td>User-sent data are invalid.</td>
     </tr>
     <tr>
-      <td>ClientError</td><td>4XX</td><td>Server returns response code which is not specified above</td>
-    </tr>
-    <tr>
-      <td>ServerError</td><td>5XX</td><td>Server returns response code which is not specified above</td>
+      <td>ServerError</td><td>5XX</td><td>An exception happened while processing a request.</td>
     </tr>
   </tbody>
 </table>
+
+## Development
+
+```sh
+git clone <repo-url>
+cd fakturoid-ruby
+bundle
+bundle exec rake # Run tests
+bundle exec rake build # Test the package building process
+```