t2_airtime 0.2.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56a617eb55e1c54d012e7e70567160d234582bf6
-  data.tar.gz: ba92d2ed04fa29d29ec939f4566abd3902b78475
+  metadata.gz: d5be1d81ae20b8777de2203112eb858f005a2d5c
+  data.tar.gz: 2cddc813b0f043c501119d1f654e921248a2daf9
 SHA512:
-  metadata.gz: 21125b5e0d8e5a868b3dbf879a3160bffe290b097ca22f0475df99f0f60a4e7366ec18c2427af412798162e5e0989a01d9d2cebe7d5999add10a21fb60a7050c
-  data.tar.gz: a41c43d24e395fc48225060f462dfcf4e71f4a5e82b05758be0f6fd3dafb4443a5af859c10758f8172a3fdc62cba0a7a90199f35ad757e43fb25e2a16ac3f9f6
+  metadata.gz: a0a908f95d48701e5c4df6784c0158c5bf3d71fb06b4d771f2d0948e0eda622f6aeacb8dac184a0cb501e15738efe23ffee0dc7c92f143faa0a3db78eac3c110
+  data.tar.gz: 724d54f3f1b4469f4e40942a102df63636a9e095bfc3f5bb4c4120ead886d48cc1e7ee5150b0ac79c87dacbd24a5be58f0346bde26486d4989d0948cfb93ec33

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2017 matteolc
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+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.

data/README.md

@@ -8,18 +8,9 @@ This gem is a convenience wrapper around the Airtime API. Requirement is that Tw
 
 ## Usage
 
-Create a new rails application (the flags used here are just for simplicity):
-
-    rails new airtime \
-        --skip-active-record \
-        --skip-yarn \
-        --skip-action-cable \
-        --skip-sprockets \
-        --skip-spring \
-        --skip-coffee \
-        --skip-javascript \
-        --skip-turbolinks \
-        --api 
+Create a new rails application:
+
+    rails new t2_airtime
 
 Add this line to your application's Gemfile:
 
@@ -35,7 +26,6 @@ Create a `.env` file with the required information:
 
     T2_SHOP_USER=
     T2_AIRTIME_KEY=
-    T2_CURRENCY=
 
 Start the server: `bundle exec puma -C config/puma.rb`
 
@@ -44,39 +34,431 @@ Start the server: `bundle exec puma -C config/puma.rb`
 The following routes are mada available to your application when you mount the API engine in `config/routes.rb`:
 
 ```ruby
-mount T2Airtime::Engine => '/airtime'
+mount T2Airtime::Engine => '/t2_airtime'
 ```
 
-    http://localhost:3000/airtime/transactions
-    http://localhost:3000/airtime/transactions/<id>
-    http://localhost:3000/airtime/countries
-    http://localhost:3000/airtime/<country_id>/operators
-    http://localhost:3000/airtime/<operator_id>/products
+* `/t2_airtime/account` [Account information](#account_info)
+* `/t2_airtime/countries` [List of all countries offered](#country_list)
+* `/t2_airtime/countries/<country_id>/operators` [List of all operators available for a certain country](#operator_list)
+* `/t2_airtime/countries/<country_id>/operators/<operator_id>/products` [List of all products available for a certain operator](#product_list)
+* `/t2_airtime/transactions` [List all transactions](#transaction_list)
+* `/t2_airtime/transactions/<id>` [Show a transaction](#transaction_show)
     
-### Helpers
+### API Object
 
-Main API helper:
+You can access the Airtime API in Ruby as:
 
 ```ruby
 api = T2Airtime::API.api
 ```
 
-[TBC]   
+The following methods are available to the `api` object:
 
-## Development
+* `ping` [Test the connection to the Airtime API](#ping)
+* `account_info` [Information regarding your TransferTo account](#account_info)
+* `country_list` [Retrieve available countries](#country_list)
+* `operator_list` [Retrieve all operators available for a certain country](#operator_list)
+* `product_list` [Retrieve all products available for a certain operator](#product_list)
+* `transaction_list` [Retrieve the list of transactions performed within a date range](#transaction_list)
+* `transaction_info` [Retrieve available information on a specific transaction](#transaction_info)
+* `topup` Recharge a destination number with a specified product.
+* `msisdn_info` Retrieve various information of a specific MSISDN as well as the list of all products configured for your specific account and the destination operator of the MSISDN.
+* `reserve_id` Reserve a transaction ID in the system. Maybe used in a topup operation.
+* `get_id_from_key` Retrieve the ID of a transaction previously performed based on the key used in the request at that time.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Each method returns an object with the following properties:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+* `success?` `true` if the request was successful.
+* `status` The HTTP status of the reply. `200` indicates a successful request.
+* `error_code` The error code of the request. `0` indicates a successful request.
+* `error_message` The error message of the request. `Transaction successful` indicates a successful request.
+* `url` The full URL of the request.
+* `information` The response body as a hash.
+* `auth_key` The authorization key used in the request.
+* `headers` The HTTP Headers of the reply.
+* `raw` The raw body of the reply.
 
-## Contributing
+<a name="ping"></a>
+#### Ping
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/t2_airtime. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+This method can be used for keep-alive. To test the connection with the API:
 
-## License
+```ruby
+irb(main)> response= T2Airtime::API.api.ping
+irb(main)> response.success?
+=> true
+```
+
+<a name="account_info"></a>
+#### Account Information
+
+The `account_info` method retrieves the various information regarding your TransferTo account. 
+To format the response as JSON-API you can call `T2Airtime::Account.serialize(data)`.
+
+From a Rails console (or Ruby file):
+
+```ruby
+irb(main)> response= T2Airtime::API.api.account_info
+irb(main)> account= T2Airtime::Account.serialize(response.data)
+```
+
+The serializer returns the following JSON representation of your account:
+
+```ruby
+{
+    "type": "accounts",
+    # Account login name
+    "id": ACCOUNT_ID,
+    "attributes": {
+        # Account type: "Master" (main account) or "Retailer" (subaccount)
+        "type": ACCOUNT_TYPE 
+        # Account login name
+        "name": ACCOUNT_NAME,
+        # Account currency (USD, GBP, EUR, etc…)
+        "currency": ACCOUNT_CURRENCY,
+        # For main account: returns the account’s remaining balance.
+        # For sub-account: returns the account’s remaining limit balance
+        # of the day if a daily limit is fixed. Else, returns the account
+        # remaining balance
+        "balance": ACCOUNT_BALANCE,
+        # For main account: returns the total remaining balance (sum 
+        # of all sub-accounts and current master).
+        # For sub-account: 
+        # 1. If balance is shared and daily limit is fixed: returns the fixed daily limit amount 
+        # 2. If balance is shared but daily limit is not fixed: returns "No Limit"
+        # 3. Else if balance is not shared: returns the remaining balance        
+        "wallet": ACCOUNT_WALLET,
+        # The time at which the information was fetched. 
+        # Can be used for caching purposes.
+        "fetched-at": TIMESTAMP
+    }
+}
+{{</ highlight >}}
+
+From a browser:
+[http://localhost:3000/account](/)
+
+![JSON response](/img/account_json.png) 
+
+<a name="country_list"></a>
+#### Country List
+
+The `country_list` method retrieves the countries offered in your TransferTo price list. 
+To format the response as JSON-API you can call `T2Airtime::Country.serialize(data)`.
+
+From a Rails console (or Ruby file):
+
+```ruby
+irb(main)> response= T2Airtime::API.api.country_list
+irb(main)> countries= T2Airtime::Country.serialize(response.data)
+```
+
+The serializer returns the following JSON representation of a country:
+
+```ruby
+{
+    "type": "countries",
+    # Unique Airtime ID for the country
+    "id": COUNTRY_ID,
+    "attributes": {
+        # The country name
+        "name": COUNTRY_NAME, 
+        # The ISO 3166-1 country alpha-3, https://it.wikipedia.org/wiki/ISO_3166-1_alpha-3
+        # Can be used for unique country identification.
+        "alpha3": COUNTRY_ALPHA3,
+        # The time at which the country was fetched. 
+        # Can be used for caching purposes.
+        "fetched-at": TIMESTAMP
+    },
+    "relationships": {
+        "operators": { "links": { "related": "/countries/COUNTRY_ID/operators" } }
+    }
+}
+```
+
+The `relationships` section of the response provides a link you can use to navigate the country operators.
+
+From a browser:
+[http://localhost:3000/countries](/)
+
+![JSON response](/img/country_list_json.png)
+
+<a name="operator_list"></a>
+#### Operator List
+
+The `operator_list` method retrieves the operators available for a certain country. 
+To format the response as JSON-API you can call `T2Airtime::Operator.serialize(data)`.
+
+From a Rails console (or Ruby file):
+
+```ruby
+irb(main)> response= T2Airtime::API.api.operator_list countries.shuffle.first["id"]
+irb(main)> operators= T2Airtime::Operator.serialize(response.data)
+```
+
+The serializer returns the following JSON representation of an operator:
+
+```ruby
+{
+    "type": "operators",
+    # Unique Airtime ID for the operator
+    "id": OPERATOR_ID,
+    "attributes": {
+        # The operator name
+        "name": OPERATOR_NAME, 
+        # The time at which the operator was fetched. 
+        # Can be used for caching purposes.        
+        "fetched-at": TIMESTAMP
+    },
+    "links": {
+        # The URL at which you can retrieve the operator's logo
+        logo: OPERATOR_LOGO_URL
+    },
+    "relationships": {
+        "country": { "data": { "type": "countries", "id": COUNTRY_ID } },
+        "products": { "links": { "related": "/countries/COUNTRY_ID/operators/OPERATOR_ID/products" } }              
+    },
+    "included": [
+        {
+            "type": "countries",
+            "id": COUNTRY_ID,
+            "attributes": {
+                "name": COUNTRY_NAME,             
+                "alpha3": COUNTRY_ALPHA3
+            }                
+        }
+    ] 
+}
+```            
+
+* The `relationships` section of the response provides a link you can use to navigate the operator products.
+* The `included` section of the response provides all the information regarding the operator's country.
+
+From a browser:
+[http://localhost:3000/countries/COUNTRY_ID/operators](/)
+
+![JSON response](/img/operator_list_json.png)
+
+<a name="product_list"></a>
+#### Product List
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The `product_list` method retrieves the products available for a certain operator. 
+To format the response as JSON-API you can call `T2Airtime::Product.serialize(data)`.
 
-## Code of Conduct
+From a Rails console (or Ruby file):
+
+```ruby
+irb(main)> response= T2Airtime::API.api.product_list operators.shuffle.first["id"]
+irb(main)> products= T2Airtime::Product.serialize(response.data)
+```
+
+The serializer returns the following JSON representation of a product:
+
+```ruby
+{
+    "type": "products",
+    # Airtime ID for the product. Attention! It is only unique within
+    # the scope of the operator
+    "id": PRODUCT_ID, 
+    "attributes": {
+        # The product name, or face value for display, es. 5EUR
+        "name": PRODUCT_NAME, 
+        # Currency of the destination country
+        "currency": PRODUCT_CURRENCY,
+        # The face value of the product (same as id)
+        "local-price": PRODUCT_LOCAL_PRICE,
+        # The retail price of the product
+        "retail-price": PRODUCT_RETAIL_PRICE,
+        # The wholesale price  (also known as your cost) of the product
+        "wholesale-price": PRODUCT_WHOLESALE_PRICE,  
+        # The time at which the operator was fetched. 
+        # Can be used for caching purposes.                     
+        "fetched-at": TIMESTAMP
+    },
+    "relationships": {
+        "country": { "data": { "type": "countries", "id": COUNTRY_ID } },
+        "operator": { "data": { "type": "operators", "id": OPERATOR_ID } }
+    },
+    "included": [
+        {
+            "type": "countries",
+            "id": COUNTRY_ID,
+            "attributes": {
+                "name": COUNTRY_NAME,
+                "alpha3": COUNTRY_ALPHA3
+            }                
+        },
+        {
+            "type": "operators",
+            "id": OPERATOR_ID,
+            "attributes": { "name": OPERATOR_NAME },
+            "links": { "logo": OPERATOR_LOGO_URL }              
+        }
+    ]
+    }
+}
+```            
+
+* The `relationships` section of the response provides a link you can use to navigate the product `included` relationships.
+* The `included` section of the response provides all the information regarding the product's country and operator.
+
+From a browser:
+[http://localhost:3000/countries/COUNTRY_ID/operators/OPERATOR_ID/products](/)
+
+![JSON response](/img/product_list_json.png)
+
+<a name="transaction_list"></a>
+#### Transaction List
+
+The `transaction_list` method retrieves all transaction within the specified time-range. 
+To format the response as JSON-API you can call `T2Airtime::Transaction.serialize(data)`.
+
+From a Rails console (or Ruby file):
+
+```ruby
+irb(main)> response= T2Airtime::API.api.transaction_list
+irb(main)> transactions= T2Airtime::Transaction.serialize(response.data)
+```
+
+From a browser:
+[http://localhost:3000/transactions](/)
+
+![JSON response](/img/transaction_list_json.png)
+
+
+<a name="transaction_info"></a>
+#### Transaction Information
+
+The `transaction_info` method retrieves information regarding a certain transaction. 
+To format the response as JSON-API you can call `T2Airtime::Transaction.serialize_one(data)`.
+
+From a Rails console (or Ruby file):
+
+```ruby
+irb(main)> response= T2Airtime::API.api.transaction_info
+irb(main)> transactions= T2Airtime::Transaction.serialize_one(response.data)
+{{</ highlight >}}
+
+The serializer returns the following JSON representation of a transaction:
+
+```ruby
+{
+    type: "transactions",
+    # Unique Airtime ID for the transaction
+    id: TRANSACTION_ID,
+    attributes: {
+        # The international phone number or name of 
+        # the user (sender) requesting to credit a phone 
+        # number
+        "msisdn": TRANSACTION_MSISDN,
+        # Destination MSISDN (usually recipient phone number)
+        "destination-msisdn": TRANSACTION_DESTINATION_MSISDN,
+        # Authentication key used during the transaction
+        "transaction-authentication-key": TRANSACTION_AUTHENTICATION_KEY,
+        # Error code for the transaction
+        "transaction-error-code": TRANSACTION_ERROR_CODE,
+        # Description of the error code for the transaction
+        "transaction-error-txt": TRANSACTION_ERROR_TEXT,
+        # Reference of the operator (returned only if available)
+        "reference-operator": TRANSACTION_REFERENCE_OPERATOR,
+        # Returns the value requested to the operator 
+        # (equals to product_requested in case of successful
+        # transaction). It equals to 0 when Top-up 
+        # failed.
+        "actual-product-sent": TRANSACTION_PRODUCT_SENT,
+        # Recipient SMS
+        # Returns the custom message appended to the 
+        # default notification SMS sent to the recipient
+        "sms": TRANSACTION_SMS,
+        # Value of the customized field cid1 sent in the Top-up request
+        "cid1": TRANSACTION_CID1,
+        # Value of the customized field cid2 sent in the Top-up request
+        "cid2": TRANSACTION_CID2,
+        # Value of the customized field cid3 sent in the Top-up request
+        "cid3": TRANSACTION_CID3,
+        # Date of the transaction (GMT)
+        "date": TRANSACTION_DATE,
+        # Currency of the account from which the transaction is requested
+        "originating-currency": TRANSACTION_ORIGINATING_CURRENCY,
+        # Currency of the destination country
+        "destination-currency": TRANSACTION_DESTINATION_CURRENCY,
+        # Type of product returned ("Yes", default "No" if not set)
+        "pin-based": TRANSACTION_PIN_BASED,
+        # Final amount received by recipient. Indicative value only
+        "local-info-amount": TRANSACTION_LOCAL_INFO_AMOUNT,
+        # Local currency in destination
+        "local-info-currency": TRANSACTION_LOCAL_INFO_CURRENCY,
+        # Value of the transaction before tax and service 
+        # fee in local currency.
+        "local-info-amount": TRANSACTION_LOCAL_INFO_AMOUNT,
+        # The time at which the transaction was fetched. 
+        # Can be used for caching purposes.         
+        "fetched-at": TIMESTAMP
+    },
+    relationships: {
+        country: { data: { type: "countries", id: COUNTRY_ID } },
+        operator: { data: { type: "operators", id: OPERATOR_ID } },
+        product: { data: { type: "products", id: PRODUCT_ID } }
+    },
+    included: [
+        {
+            type: "countries",
+            id: COUNTRY_ID,
+            attributes: {
+                "name": COUNTRY_NAME,
+                "alpha3": COUNTRY_ALPHA3
+            }                
+        },
+        {
+            type: "operators",
+            id: OPERATOR_ID,
+            attributes: { "name": OPERATOR_NAME },
+            links: { logo: OPERATOR_LOGO_URL }               
+        },
+        {
+            type: "products",
+            id: PRODUCT_ID,
+            attributes: {
+                "name": PRODUCT_NAME,
+                "currency": PRODUCT_CURRENCY,
+                "wholesale-price": PRODUCT_WHOLESALE_PRICE,
+                "retail-price": PRODUCT_RETAIL_PRICE,
+                "local-price": PRODUCT_LOCAL_PRICE
+            }              
+        }
+    ]
+}
+```            
+
+* The `relationships` section of the response provides a link you can use to navigate the product `included` relationships.
+* The `included` section of the response provides all the information regarding the product's country and operator.
+
+From a browser:
+[http://localhost:3000/transactions/TRANSACTION_ID](/)
+
+![JSON response](/img/transaction_list_json.png)  
+
+## Testing
+
+Clone this repository and export your secrets:
+
+    $> export T2_SHOP_USER=
+    $> export T2_AIRTIME_KEY=
+
+Execute:
+
+    rake
+
+To execute the test application:
+
+    cd spec/dummy
+
+Start the server: `puma -C config/puma.rb`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/matteolc/t2_airtime.
+
+## License
 
-Everyone interacting in the T2Airtime project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/t2_airtime/blob/master/CODE_OF_CONDUCT.md).
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -1,6 +1,26 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
 
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'T2Airtime'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.md')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+load 'rails/tasks/statistics.rake'
+
+require 'bundler/gem_tasks'
+
+require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec
+
+