# Qismo Ruby

A Ruby API wrapper for Qiscus Omnichannel API

## Installation

Install the gem and add to the application's Gemfile by executing:

```bash
bundle add qismo
```

## Usage

### 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
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
```

Then, start requesting to any endpoint yg want

```ruby
params = {
  channel: { id: 12345, source: "wa" },
  status: "unresolved",
  serve_status: "served",
  is_handled_by_bot: false,
}

rooms = Qismo.rooms(params)
```

If your app manage multiple app id, you initialize the client like below

```ruby
client = Qismo::Client.new(app_id: "YOUR_ACCOUNT_APP_ID", secret_key: "YOUR_ACCOUNT_SECRET_KEY")
```

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

### Client configuration

**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.url = "https://qismo.qiscus.com"
```

**logger**

You can also log the request and response the any HTTP request you make in Qismo ruby by using this configuration

```ruby
require "logger"

client.logger = Logger.new($stdout)
```

**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
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 }
```

You can also customize the instrumentation's namespace by using this configuration

```ruby
client.instrumentation = { instrumenter: ActiveSupport::Notifications.instrumenter, namespace: "qiscus.http_request" }
```

**timeout**

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 }
```

Global timeouts let you set an upper bound of how long a request can take

```ruby
client.timeout = 5 # in seconds
```

**proxy**

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

```ruby
client.proxy = ["proxy-hostname.local", 8080]
```

Proxy needs authentication?

```ruby
client.proxy = ["proxy-hostname.local", 8080, "username", "password"]
```

### Handling pagination

Some of the Qiscus Omnichannel API will return list of data with pagination. To handle the pagination, you can to that like this example:

```ruby
all_rooms = []
rooms = client.rooms
all_rooms.append(rooms)

while rooms.has_next_page?
  rooms = rooms.next_page
  all_rooms.append(rooms)
end
```

### 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
```