KaChing::Client

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
• Usage (API V1)
  • Setup the client
    • Customize Faraday
  • Saldo
    • current
  • Bookings
    • deposit!
    • withdraw!
    • drop!
    • unlocked
  • Lockings
    • lock!
    • unlock!
    • all paginated
    • of_year
    • active
    • inactive
  • AuditLogs
    • of_year
    • of_year_month
    • of_year_month_day
  • Tenants
    • all
    • active
    • inactive
  • Admin
    • details
    • create!
    • drop!
    • reset!
• Development
• Contributing
• License

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

The KaChing API is a RESTful API. It uses JSON for serialization of requests and responses.

require 'bundle/setup'
require 'ka-ching-client'

client = KaChing::ApiClient.new(api_version: :v1, base_url: 'http://localhost:9292')
                           .build_client!

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)

All saldo related endpoints.

Get the current saldo for a tenant.

res = client.v1.saldo.current(tenant_account_id: 'testuser_1')
puts res # => { saldo: 100 }

All booking related endpoints.

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'}
)

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'}
)

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'
)

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, ... }]

All lockings related endpoints.

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 the last locking for a tenant by its id.

res = client.v1.lockings.unlock!(tenant_account_id: 'testuser_1')

Get all lockings for a tenant paginated.

res = client.v1.lockings.all(
  tenant_account_id: 'testuser_1',
  page: 1,
  per_page: 10,
)

Get lockings for a tenant by year.

res = client.v1.lockings.of_year(tenant_account_id: 'testuser_1', year: 2019)

Get active lockings for a tenant for a year.

res = client.v1.lockings.active(
  tenant_account_id: 'testuser_1',
  year: 2019,
)

Get inactive lockings for a tenant for a year.

res = client.v1.lockings.inactive(
  tenant_account_id: 'testuser_1',
  year: 2019,
)

All audit_logs related endpoints.

Get audit_logs for a tenant by year.

res = client.v1.audit_logs.of_year(tenant_account_id: 'testuser_1', year: 2019)

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
)

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
)

All tenants related endpoints.

Get all tenants paginated.

res = client.v1.tenants.all(page: 1, per_page: 1000)

Get all active tenants paginated.

res = client.v1.tenants.active(page: 1, per_page: 1000)

Get all inactive tenants paginated.

res = client.v1.tenants.inactive(page: 1, per_page: 1000)

All admin related endpoints, for managing tenant databases.

Details of a tenant database.

res = client.v1.admin.details(tenant_account_id: 'testuser_1')

Create a new tenant database.

res = client.v1.admin.create!(tenant_account_id: 'testuser_1')

Drop/Delete a tenant database.

res = client.v1.admin.drop!(tenant_account_id: 'testuser_1')

Reset a tenant database.

res = client.v1.admin.reset!(tenant_account_id: 'testuser_1')

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.

Bug reports and pull requests are welcome on GitHub at https://github.com/simonneutert/ka-ching-client.

See CONTRIBUTING.md.

The gem is available as open source under the terms of the MIT License.