README.md in omisego-0.9.6 vs README.md in omisego-0.10.0
- old
+ new
@@ -1,14 +1,20 @@
+
+[](https://travis-ci.org/omisego/ruby-sdk)
+[](https://badge.fury.io/rb/omisego)
+
# OmiseGO
OmiseGO is a Ruby SDK meant to communicate with an OmiseGO eWallet setup.
+For more details about the web API being wrapped by this SDK, take a look at the [OpenAPI Specification](https://ewallet.demo.omisego.io/api/docs.ui). You are free to use that web API directly if you prefer, this SDK is only provided as a convenient way to make those HTTP calls and return Ruby objects as responses.
+
## Installation
Add this line to your application's Gemfile:
-```
+```ruby
gem 'omisego'
```
And then execute:
@@ -24,30 +30,44 @@
In the end, the choice is yours and the optimal solution depends on your needs.
### Global init
-```
+```ruby
# config/initializers/omisego.rb
OmiseGO.configure do |config|
config.access_key = ENV['OMISEGO_ACCESS_KEY']
config.secret_key = ENV['OMISEGO_SECRET_KEY']
config.base_url = ENV['OMISEGO_BASE_URL']
end
```
If initialized this way, the `OmiseGO` classes can be used without specifying the client.
+```ruby
+user = OmiseGO::User.find(provider_user_id: 'provider_user_id01')
```
-user = OmiseGO::User.find(provider_user_id: 'some_uuid')
+
+### Client init
+
+With this approach, the client needs to be passed in every call and will be used as the call initiator.
+
+```ruby
+client = OmiseGO::Client.new(
+ access_key: ENV['OMISEGO_ACCESS_KEY'],
+ secret_key: ENV['OMISEGO_SECRET_KEY'],
+ base_url: ENV['OMISEGO_BASE_URL']
+)
+
+user = OmiseGO::User.find(provider_user_id: 'provider_user_id01', client: client)
```
-### Logging
+### Logging Configuration
The Ruby SDK comes with the possibility to log requests to the eWallet. For example, within a Rails application, the following can be defined:
-```
+```ruby
# config/initializers/omisego.rb
OmiseGO.configure do |config|
config.access_key = ENV['OMISEGO_ACCESS_KEY']
config.secret_key = ENV['OMISEGO_SECRET_KEY']
config.base_url = ENV['OMISEGO_BASE_URL']
@@ -75,203 +95,229 @@
Cache-Control: max-age=0, private, must-revalidate
{"version":"1","success":true,"data":{"object":"authentication_token","authentication_token":[FILTERED]}}
```
-### Client init
+## Usage
-With this approach, the client needs to be passed in every call and will be used as the call initiator.
+All the calls below will communicate with the OmiseGO wallet specified in the `base_url` configuration. They will either return an instance of `OmiseGO:Error` or of the appropriate model (`User`, `Balance`, etc.), see [the list of models](#models) for more information.
-```
-client = OmiseGO::Client.new(
- access_key: ENV['OMISEGO_ACCESS_KEY'],
- secret_key: ENV['OMISEGO_SECRET_KEY'],
- base_url: ENV['OMISEGO_BASE_URL']
-)
+__The method `#error?` can be used on any model to check if it's an error or a valid result.__
-user = OmiseGO::User.find(provider_user_id: 'some_uuid', client: client)
-```
-## Usage
+### Understanding Idempotency
-All the calls below will communicate with the OmiseGO wallet specified in the `base_url` configuration. They will either return an instance of `OmiseGO:Error` or of the appropriate model (`User`, `Balance`, etc.), see [the list of models](#models) for more information.
+Some of the calls in the web API (and in the methods below) contain a parameter called `idempotency_token`.
-__The method `#error?` can be used on any model to check if it's an error or a valid result.__
+### Understanding wallet types
+### Understanding Metadata and Encrypted Metadata
+
+
+### All available methods
+
+- [Find a user](#find-user)
+- [Create a user](#create-user)
+- [Update a user](#update-user)
+- [Get all wallets for a user](#get-all-wallets-for-a-user)
+- [Loggging in a user](#login-user)
+- [Get all wallets](#all-wallets)
+- [Credit a user's wallet](#credit-wallet)
+- [Debit a user's wallet](#debit-wallet)
+
### Managing Users
-#### Find
+#### Find User
Retrieve a user from the eWallet API.
-```
+```ruby
user = OmiseGO::User.find(
- provider_user_id: 'some_uuid'
+ provider_user_id: 'provider_user_id01',
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
```
Returns either:
- An `OmiseGO::User` instance
- An `OmiseGO::Error` instance
-#### Create
+#### Create User
Create a user in the eWallet API database. The `provider_user_id` is how a user is identified and cannot be changed later on.
-```
+```ruby
user = OmiseGO::User.create(
- provider_user_id: 'some_uuid',
+ provider_user_id: 'provider_user_id01',
username: 'john@doe.com',
metadata: {
first_name: 'John',
last_name: 'Doe'
- }
+ }, # optional, defaults to {}
+ encrypted_metadata: {}, # optional, defaults to {}
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
```
Returns either:
- An `OmiseGO::User` instance
- An `OmiseGO::Error` instance
-#### Update
+#### Update User
Update a user in the eWallet API database. All fields need to be provided and the values in the eWallet database will be replaced with the sent ones (behaves like a HTTP `PUT`). Sending `metadata: {}` in the request below would remove the `first_name` and `last_name` fields for example.
-```
+```ruby
user = OmiseGO::User.update(
- provider_user_id: 'some_uuid',
+ provider_user_id: 'provider_user_id01',
username: 'jane@doe.com',
- metadata: {
- first_name: 'Jane',
- last_name: 'Doe'
- }
+ metadata: {}, # optional, defaults to {}
+ encrypted_metadata: {}, # optional, defaults to {}
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
+
+# or
+
+user = OmiseGO::User.find(provider_user_id: 'provider_user_id01')
+user = user.update(
+ username: 'jane@doe.com',
+ metadata: {}, # optional, defaults to {}
+ encrypted_metadata: {}, # optional, defaults to {}
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
+)
```
Returns either:
- An `OmiseGO::User` instance
- An `OmiseGO::Error` instance
-### Managing Sessions
+#### Get all wallets for a user
-#### Login
+Retrieve a list of wallets (with only one primary wallet for now) containing a list of balances.
-Login a user and retrieve an `authentication_token` that can be passed to a mobile client to make calls to the eWallet API directly.
+```ruby
+wallets = OmiseGO::User.wallets(
+ provider_user_id: 'provider_user_id01',
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
+)
-```
-auth_token = OmiseGO::User.login(
- provider_user_id: 'some_uuid'
+# or
+
+user = OmiseGO::User.find(provider_user_id: 'provider_user_id01')
+wallets = user.wallets(
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
```
Returns either:
-- An `OmiseGO::AuthenticationToken` instance
+- An `OmiseGO::List` of `OmiseGO::Wallet` instances
- An `OmiseGO::Error` instance
-### Managing Balances
+### Managing Sessions
-- [All](#All)
-- [Credit](#Credit)
-- [Debit](#Debit)
+#### Login User
-#### All
+Login a user and retrieve an `authentication_token` that can be passed to a mobile client to make calls to the eWallet API directly.
-Retrieve a list of addresses (with only one address for now) containing a list of balances.
+```ruby
+auth_token = OmiseGO::User.login(
+ provider_user_id: 'provider_user_id01',
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
+)
-```
-address = OmiseGO::Balance.all(
- provider_user_id: 'some_uuid'
+# or
+
+user = OmiseGO::User.find(provider_user_id: 'provider_user_id01')
+auth_token = user.login(
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
```
Returns either:
-- An `OmiseGO::Address` instance
+- An `OmiseGO::AuthenticationToken` instance
- An `OmiseGO::Error` instance
-#### Credit
+### Managing Wallets
-Transfer the specified amount (as an integer, down to the `subunit_to_unit`) from the master wallet to the specified user's wallet. In the following methods, an idempotency token is used to ensure that one specific credit/debit occurs only once. The implementer is responsible for ensuring that those idempotency tokens are unique - sending the same one two times will prevent the second transaction from happening.
+#### All Wallets
-```
-address = OmiseGO::Balance.credit(
- provider_user_id: 'some_uuid',
- token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
- amount: 10_000,
- idempotency_token: "123",
- metadata: {}
+Retrieve a list of wallets (with only one address for now) containing a list of balances.
+
+```ruby
+wallets = OmiseGO::Wallet.all(
+ provider_user_id: 'provider_user_id01',
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
```
-To use the primary balance of a specific account instead of the master account's as the sending balance, specify an `account_id`:
+Returns either:
+- An `OmiseGO::List` of `OmiseGO::Wallet` instances
+- An `OmiseGO::Error` instance
-```
-address = OmiseGO::Balance.credit(
- account_id: 'account_uuid',
- provider_user_id: 'some_uuid',
- token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
- amount: 10_000,
- idempotency_token: "123",
- metadata: {}
-)
-```
+#### Credit Wallet
-#### Debit
+Transfer the specified amount (as an integer, down to the `subunit_to_unit`) from an account's wallet to a user's wallet (defaults to the user's primary wallet).
-Transfer the specified amount (as an integer, down to the `subunit_to_unit`) from the specified user's wallet back to the master wallet.
+__In the following methods, an idempotency token is used to ensure that one specific credit/debit occurs only once. The implementer is responsible for ensuring that those idempotency tokens are unique - sending the same one two times will prevent the second transaction from happening__
-```
-address = OmiseGO::Balance.debit(
- provider_user_id: 'some_uuid',
- token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
+For both the user and the account, an address can be specified to use a different wallet than the primary one.
+
+```ruby
+wallet = OmiseGO::Wallet.credit(
+ provider_user_id: 'provider_user_id01',
+ user_address: nil, # optional, defaults to the user's primary wallet
+ account_id: 'acc_01C4T2Y5SFYASXXYANV96MQQC9',
+ account_address: nil, # optional, defaults to the account's primary wallet
+ token_id: 'tok_OMG_01ccmny8yne44b188287d44498',
amount: 10_000,
idempotency_token: "123",
- metadata: {}
+ metadata: {}, # optional, defaults to {}
+ encrypted_metadata: {}, # optional, defaults to {}
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
```
-To use the primary balance of a specific account instead of the master account as the receiving balance, specify an `account_id`:
+Returns either:
+- An `OmiseGO::List` of `OmiseGO::Wallet` instances (containing the 2 wallets involved in the transaction)
+- An `OmiseGO::Error` instance
-```
-address = OmiseGO::Balance.debit(
- account_id: 'account_uuid',
- provider_user_id: 'some_uuid',
- token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
- amount: 10_000,
- idempotency_token: "123",
- metadata: {}
-)
-```
+#### Debit Wallet
-By default, points won't be burned and will be returned to the account's primary balance (either the master's balance or the account's specified with `account_id`). If you wish to burn points, send them to a burn address. By default, a burn address identified by `'burn'` is created for each account which can be set in the `burn_balance_identifier` field:
+Transfer the specified amount (as an integer, down to the `subunit_to_unit`) from the specified user's primary wallet back to the specified account's primary wallet. If you wish to use secondary or burn wallets, they can be specified in `user_address` and `account_address`.
-```
-address = OmiseGO::Balance.debit(
- account_id: 'account_uuid',
- burn_balance_identifier: 'burn',
- provider_user_id: 'some_uuid',
- token_id: 'OMG:5e9c0be5-15d1-4463-9ec2-02bc8ded7120',
+```ruby
+wallet = OmiseGO::Wallet.debit(
+ provider_user_id: 'provider_user_id01',
+ user_address: nil, # optional, defaults to the user's primary wallet
+ account_id: 'acc_01C4T2Y5SFYASXXYANV96MQQC9',
+ account_address: nil, # optional, defaults to the account's primary wallet
+ token_id: 'tok_OMG_01ccmny8yne44b188287d44498',
amount: 10_000,
idempotency_token: "123",
- metadata: {}
+ metadata: {}, # optional, defaults to {}
+ encrypted_metadata: {}, # optional, defaults to {}
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
```
-### Getting settings
+By default, points won't be burned and will be returned to the specified account's primary balance. If you wish to burn points, send them to a burn address. You may also send them to a secondary wallet if you prefer.
-#### All
-
-Retrieve the settings from the eWallet API.
-
-```
-settings = OmiseGO::Setting.all
-```
-
Returns either:
-- An `OmiseGO::Setting` instance
+- An `OmiseGO::List` of `OmiseGO::Wallet` instances (containing the 2 wallets involved in the transaction)
- An `OmiseGO::Error` instance
-
### Listing transactions
#### Params
Some parameters can be given to the two following methods to customize the returned results. With them, the list of results can be paginated, sorted and searched.
@@ -279,13 +325,13 @@
- `page`: The page you wish to receive.
- `per_page`: The number of results per page.
- `sort_by`: The sorting field. Available values: `id`, `status`, `from`, `to`, `created_at`, `updated_at`
- `sort_dir`: The sorting direction. Available values: `asc`, `desc`
- `search_term`: A term to search for in ALL of the searchable fields. Conflict with `search_terms`, only use one of them. See list of searchable fields below (same as `search_terms`).
-- `search_terms`: A hash of fields to search in:
+- `search_terms`: A hash of fields to search in:
-```
+```ruby
{
search_terms: {
from: "address_1"
}
}
@@ -295,84 +341,99 @@
#### All
Get the list of transactions from the eWallet API.
-```
+```ruby
transaction = OmiseGO::Transaction.all
```
Returns either:
- An `OmiseGO::List` instance of `OmiseGO::Transaction` instances
- An `OmiseGO::Error` instance
Parameters can be specified in the following way:
+```ruby
+transaction = OmiseGO::Transaction.all(
+ params: {
+ page: 1,
+ per_page: 10,
+ sort_by: 'created_at',
+ sort_dir: 'desc',
+ search_terms: {
+ from: "address_1",
+ to: "address_2",
+ status: "confirmed"
+ }
+ },
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
+)
```
-transaction = OmiseGO::Transaction.all(params: {
- page: 1,
- per_page: 10,
- sort_by: 'created_at',
- sort_dir: 'desc',
- search_terms: {
- from: "address_1",
- to: "address_2",
- status: "confirmed"
- }
-})
-```
#### All for user
Get the list of transactions for a specific provider user ID from the eWallet API.
-```
+```ruby
transaction = OmiseGO::Transaction.all(
params: {
- provider_user_id: "some_uuid"
- }
+ provider_user_id: "provider_user_id01"
+ },
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
)
```
Returns either:
- An `OmiseGO::List` instance of `OmiseGO::Transaction` instances
- An `OmiseGO::Error` instance
Parameters can be specified in the following way:
+```ruby
+transaction = OmiseGO::Transaction.all(
+ params: {
+ provider_user_id: "provider_user_id01",
+ page: 1,
+ per_page: 10,
+ sort_by: 'created_at',
+ sort_dir: 'desc',
+ search_terms: {
+ from: "address_1",
+ status: "confirmed"
+ }
+ },
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config
+)
```
-transaction = OmiseGO::Transaction.all(params: {
- provider_user_id: "some_uuid",
- page: 1,
- per_page: 10,
- sort_by: 'created_at',
- sort_dir: 'desc',
- search_terms: {
- from: "address_1",
- status: "confirmed"
- }
-})
-```
Since those transactions are already scoped down to the given user, it is NOT POSSIBLE to specify both `from` AND `to` in the `search_terms`. Doing so will result in the API ignoring both of those fields for the search.
-## Models
+### Getting settings
-Here is the list of all the models available in the SDK with their attributes.
+#### All
-### `OmiseGO::Address`
+Retrieve the settings from the eWallet API.
-Attributes:
-- `address` (string)
-- `balances` (array of OmiseGO::Balance)
+```ruby
+settings = OmiseGO::Setting.all(
+ client: nil # optional, defauls to nil and uses the client
+ # defined in config)
+)
+```
-### `OmiseGO::Balance`
+Returns either:
+- An `OmiseGO::Setting` instance
+- An `OmiseGO::Error` instance
-Attributes:
-- `amount` (integer)
-- `minted_token` (OmiseGO::MintedToken)
+## Models
+Here is the list of all the models available in the SDK with their attributes.
+
### `OmiseGO::AuthenticationToken`
Attributes:
- `authentication_token` (string)
@@ -388,46 +449,90 @@
Attributes:
- `data` (array of models)
- `pagination` (OmiseGO::Pagination)
-### `OmiseGO::MintedToken`
+### `OmiseGO::Token`
Attributes:
+- `id` (string)
- `symbol` (string)
- `name` (string)
- `subunit_to_unit` (integer)
+- `metadata` (object)
+- `encrypted_metadata` (object)
+### `OmiseGO::Wallet`
+
+Attributes:
+- `address` (string)
+- `balances` (array of OmiseGO::Wallet)
+- `socket_topic` (string, the channel for this wallet's events)
+- `name` (string, the name of the wallet)
+- `identifier` (string, the type of the wallet)
+- `metadata` (object)
+- `encrypted_metadata` (object)
+- `user_id` (string, user owning the wallet if applicable)
+- `user` (`OmiseGO::User`)
+- `account_id` (string, account owning the wallet if applicable)
+- `account` (`OmiseGO::Account`)
+- `created_at` (string)
+- `updated_at` (string)
+
+### `OmiseGO::Balance`
+
+Attributes:
+- `amount` (integer)
+- `token` (`OmiseGO::Token`)
+
### `OmiseGO::User`
Attributes:
- `id` (string)
- `username` (string)
- `provider_user_id` (string)
- `metadata` (hash)
+- `metadata` (object)
+- `encrypted_metadata` (object)
+### `OmiseGO::Account`
+
+Attributes:
+- `id` (string)
+- `parent_id` (string)
+- `name` (string)
+- `description` (string)
+- `master` (boolean)
+- `avatar` (hash)
+- `metadata` (object)
+- `encrypted_metadata` (object)
+- `created_at` (string)
+- `updated_at` (string)
+
### `OmiseGO::Exchange`
- `rate` (integer)
### `OmiseGO::TransactionSource`
- `address` (string)
- `amount` (integer)
-- `minted_token` (`OmiseGO::MintedToken`)
+- `token` (`OmiseGO::Token`)
### `OmiseGO::Transaction`
- `id` (string)
- `idempotency_token` (string)
- `amount` (integer)
-- `minted_token` (`OmiseGO::MintedToken`)
+- `token` (`OmiseGO::Token`)
- `from` (`OmiseGO::TransactionSource`)
- `to` (`OmiseGO::TransactionSource`)
- `exchange` (`OmiseGO::Exchange`)
- `status` (string)
- `created_at` (string)
- `updated_at` (string)
+- `metadata` (object)
+- `encrypted_metadata` (object)
### `OmiseGO::Error`
Attributes:
- `code` (string)