README.md in qismo-0.1.8 vs README.md in qismo-0.5.0
- old
+ new
@@ -1,120 +1,160 @@
# Qismo Ruby
-A Ruby API wrapper for Qiscus Multichannel API
+A Ruby API wrapper for Qiscus Omnichannel API
## Installation
-Add this line to your application's Gemfile:
+Install the gem and add to the application's Gemfile by executing:
-```ruby
-gem "qismo"
-```
-
-And then execute:
-
```bash
-bundle install
+bundle add qismo
```
## Usage
-**Example for single app id**
+### Initialize and make request
+To start using Qismo ruby, you must get your account's `App ID` and `Qiscus Secret Key` which can be checked in your admin dashboard's [settings page](https://omnichannel.qiscus.com/settings). After getting these data, you can start initialize the client.
+
```ruby
-# config/initializers/qismo.rb
-# Initialization
-Qismo.init do |config|
- config.app_id = ENV["QISCUS_APP_ID"]
- config.secret_key = ENV["QISCUS_SECRET_KEY"]
- config.base_url = ENV["QISCUS_MULTICHANNEL_BASE_URL"]
+Qismo.configure do |client|
+ client.app_id = "YOU_ACCOUNT_APP_ID"
+ client.secret_key = "YOUR_ACCOUNT_SECRET_KEY"
+
+ ## Optional
+ client.url = "https://qismo.qiscus.com"
+ client.logger = { logger: Logger.new($stdout) }
+ client.instrumentation = { instrumenter: ActiveSupport::Notifications.instrumenter }
+ client.timeout = { connect: 5, write: 2, read: 5 }
+ client.proxy = ["proxy-hostname.local", 8080, "username", "password"]
end
+```
-# Get all rooms that have been waiting for a week
-rooms = Room.where(status: "waiting")
- .where("created_at >= :a_week", a_week: 1.week.ago)
+Then, start requesting to any endpoint yg want
-# Resolve the rooms
-rooms.each(Qismo::Room.resolve(&:id))
+```ruby
+params = {
+ channel: { id: 12345, source: "wa" },
+ status: "unresolved",
+ serve_status: "served",
+ is_handled_by_bot: false,
+}
+
+rooms = Qismo.rooms(params)
```
-**Example for multi app id**
+If your app manage multiple app id, you initialize the client like below
```ruby
-# Get all rooms that have been waiting for a week
-rooms = Room.includes(:qiscus_app)
- .where(status: "waiting")
- .where("created_at >= :a_week", a_week: 1.week.ago)
+client = Qismo::Client.new(app_id: "YOUR_ACCOUNT_APP_ID", secret_key: "YOUR_ACCOUNT_SECRET_KEY")
+```
-# Resolve the rooms
-rooms.each do |room|
- Qismo.new(app_id: room.qiscus_app.app_id, secret_key: room.qiscus_app.secret_key)
- Qismo::Room.resolve(room.id)
-end
+Then, start requesting to an endpoint using that `client` variable
+
+```ruby
+params = {
+ channel: { id: 12345, source: "wa" },
+ status: "unresolved",
+ serve_status: "served",
+ is_handled_by_bot: false,
+}
+
+rooms = client.rooms(params)
```
-**Nested operations**
+### Client configuration
-If you prefer to use nested operations, you can also use this package like below
+**url**
+Defaultly, Qismo ruby will use your QISCUS_OMNICHANNEL_URL env as base url. If its nil, it will use https://qismo.qiscus.com. If you need to customize URL other than that, you can pass it at client initialization
+
```ruby
-client = Qismo.new(app_id: room.qiscus_app.app_id, secret_key: room.qiscus_app.secret_key)
-client.room.resolve(id)
+client.url = "https://qismo.qiscus.com"
```
-**Requesting to unhandled API**
+**logger**
-Qiscus Multichannel is on fast development mode and at some condition, you might find this library is not handle the new API. If that happen, you can use the operations like below:
+You can also log the request and response the any HTTP request you make in Qismo ruby by using this configuration
```ruby
-Qismo.client.call("post", "/api/v2/api_endpoint", json: {}, params: {})
+require "logger"
+
+client.logger = Logger.new($stdout)
```
-**Error handling**
+**instrumentation**
+For advanced logging, you can also use laverage ActiveSupport instrumentation. If you are using Rails, you can use ActiveSupport without installing the gem by your self.
+
```ruby
-begin
- room = Qismo::Room.resolve(123456) # Not Found
-rescue Qismo::HTTPError => e
- e.message # return error message
- e.http_code # return response code
- e.http_headers # return response headers in hash
- e.http_body # return response body in hash or string
- e.http_raw_body # return raw response body in string
+ActiveSupport::Notifications.subscribe('start_request.http') d |name, start, finish, id, payload|
+ pp :name => name, :start => start.to_f, :finish => finish.to_f, :id => id, :payload => payload
end
+
+client.instrumentation = { instrumenter: ActiveSupport::Notifications.instrumenter }client.instrumentation = { instrumenter: ActiveSupport::Notifications.instrumenter }client.instrumentation = { instrumenter: ActiveSupport::Notifications.instrumenter }
```
-## Experience
+You can also customize the instrumentation's namespace by using this configuration
-This gem leverage YARD to improve text editor autocompletion
+```ruby
+client.instrumentation = { instrumenter: ActiveSupport::Notifications.instrumenter, namespace: "qiscus.http_request" }
+```
-Install YARD
+**timeout**
-```shell
-gem install yard
+By default, the Qismo ruby gem does not enforce timeout on a request. You can enable per operation timeouts (each read/write/connect call) or global timeouts (sum of all read/write/connect calls) by configuring them through the chaining API.
+
+Per operation timeouts are what `Net::HTTP` and the majority of HTTP clients do:
+
+```ruby
+client.timeout = { connect: 5, write: 2, read: 10 }
```
-Change to project directory and expose gem YARD documentation
+Global timeouts let you set an upper bound of how long a request can take
-```shell
-yard gems
+```ruby
+client.timeout = 5 # in seconds
```
-For VSCode users, you can use Solargraph gem to improve the autocompletion
+**proxy**
-## Development
+Making request behind proxy is as simple as making them directly. Just specify hostname (or IP address) of your proxy server and its port, and here you go
-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.
+```ruby
+client.proxy = ["proxy-hostname.local", 8080]
+```
-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).
+Proxy needs authentication?
-## Contributing
+```ruby
+client.proxy = ["proxy-hostname.local", 8080, "username", "password"]
+```
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/qismo. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/qismo/blob/master/CODE_OF_CONDUCT.md).
+### Handling pagination
-## License
+Some of the Qiscus Omnichannel API will return list of data with pagination. To handle the pagination, you can to that like this example:
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+```ruby
+all_rooms = []
+rooms = client.rooms
+all_rooms.append(rooms)
-## Code of Conduct
+while rooms.has_next_page?
+ rooms = rooms.next_page
+ all_rooms.append(rooms)
+end
+```
-Everyone interacting in the Qismo project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/qismo/blob/master/CODE_OF_CONDUCT.md).
+### Handling error
+
+Qismo ruby raise error while getting non successful http code from Qiscus Omnichannel API. To handle it, you follow this example:
+
+```ruby
+begin
+ client.rooms
+rescue Qismo::HTTPRequestError => e
+ e.message
+ e.status_code
+ e.response_body
+end
+```