KaChing::Client<!-- omit from toc -->
KaChing::Client is a Ruby API client for the KaChing Backend project / simonneutert/ka-ching-backend.
The client is supposed to work with the corresponding backend version. As long as it is 0.x.y the minor (x in this case) must match.
Installation
Install the gem and add to the application's Gemfile by executing:
$ bundle add ka-ching-client
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install ka-ching-client
Usage (API V1)
The KaChing API is a RESTful API. It uses JSON for serialization of requests and responses.
Setup the client
require 'bundle/setup'
require 'ka-ching-client'
client = KaChing::ApiClient.new(api_version: :v1, base_url: 'http://localhost:9292')
.build_client!
Customize Faraday
See the Faraday documentation for more information for the configuration.
require 'bundle/setup'
require 'ka-ching-client'
# configure the base url for the client
base_url = 'http://localhost:9292'
# configure the faraday client with a custom logger and your base url
custom_faraday = Faraday.new do |builder|
builder.url_prefix = base_url
builder.response :logger, nil, { bodies: { request: true, response: true } }
end
# instantiate the client for the v1 api version and the base url,
# then build the client with the custom faraday client via `build_client!`
client = KaChing::ApiClient.new(api_version: :v1, base_url: base_url)
.build_client!(faraday: custom_faraday)
Saldo
All saldo related endpoints.
current
Get the current saldo for a tenant.
res = client.v1.saldo.current(tenant_account_id: 'testuser_1')
puts res # => { saldo: 100 }
Bookings
All booking related endpoints.
deposit!
Books a deposit for a tenant.
res = client.v1.bookings.deposit!(
tenant_account_id: 'testuser_1',
amount_cents: 100,
year: 2019,
month: 11,
day: 1,
context: {'foo' => 'bar'}
)
withdraw!
Books a withdrawal for a tenant.
res = client.v1.bookings.withdraw!(
tenant_account_id: 'testuser_1',
amount_cents: 100,
year: 2019,
month: 11,
day: 1,
context: {'foo' => 'bar'}
)
drop!
Drops/Deletes a booking for a tenant by its id.
res = client.v1.bookings.drop!(
tenant_account_id: 'testuser_1',
booking_id: 'uuid-example-1234'
)
unlocked
Shows all unlocked bookings for a tenant.
res = client.v1.bookings.unlocked(tenant_account_id: 'testuser_1')
puts res # => [{ id: 'uuid-example-1234', amount_cents: 100, ... }]
Lockings
All lockings related endpoints.
lock!
Locks all unlocked bookings for a tenant by its id on (including) the given year-month-day.
res = client.v1.lockings.lock!(
tenant_account_id: 'testuser_1',
amount_cents_saldo_user_counted: '1000',
year: 2019,
month: 11,
day: 1,
context: {'foo' => 'bar'}
)
unlock!
Unlock the last locking for a tenant by its id.
res = client.v1.lockings.unlock!(tenant_account_id: 'testuser_1')
all paginated
Get all lockings for a tenant paginated.
res = client.v1.lockings.all(
tenant_account_id: 'testuser_1',
page: 1,
per_page: 10,
)
of_year
Get lockings for a tenant by year.
res = client.v1.lockings.of_year(tenant_account_id: 'testuser_1', year: 2019)
active
Get active lockings for a tenant for a year.
res = client.v1.lockings.active(
tenant_account_id: 'testuser_1',
year: 2019,
)
inactive
Get inactive lockings for a tenant for a year.
res = client.v1.lockings.inactive(
tenant_account_id: 'testuser_1',
year: 2019,
)
AuditLogs
All audit_logs related endpoints.
of_year
Get audit_logs for a tenant by year.
res = client.v1.audit_logs.of_year(tenant_account_id: 'testuser_1', year: 2019)
of_year_month
Get audit_logs for a tenant by year and month.
res = client.v1.audit_logs.of_year(
tenant_account_id: 'testuser_1',
year: 2019,
month: 11
)
of_year_month_day
Get audit_logs for a tenant by year, month and day.
res = client.v1.audit_logs.of_year(
tenant_account_id: 'testuser_1',
year: 2019,
month: 11,
day: 21
)
Tenants
All tenants related endpoints.
all
Get all tenants paginated.
res = client.v1.tenants.all(page: 1, per_page: 1000)
active
Get all active tenants paginated.
res = client.v1.tenants.active(page: 1, per_page: 1000)
inactive
Get all inactive tenants paginated.
res = client.v1.tenants.inactive(page: 1, per_page: 1000)
Admin
All admin related endpoints, for managing tenant databases.
details
Details of a tenant database.
res = client.v1.admin.details(tenant_account_id: 'testuser_1')
create!
Create a new tenant database.
res = client.v1.admin.create!(tenant_account_id: 'testuser_1')
drop!
Drop/Delete a tenant database.
res = client.v1.admin.drop!(tenant_account_id: 'testuser_1')
reset!
Reset a tenant database.
res = client.v1.admin.reset!(tenant_account_id: 'testuser_1')
Development
After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
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 the created tag, and push the .gem file to rubygems.org.
In order to record new VCR cassettes you need to bring the database into a state where the cassettes can be recorded.
It is recommended to run tests in a certain order one after another. So, you end up with the fresh cassettes you might need.
But as long as V2 is not released, you can just run the tests in the order they are defined in the test file and use the cassettes already recorded.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/simonneutert/ka-ching-client.
See CONTRIBUTING.md.
License
The gem is available as open source under the terms of the MIT License.