oushodh 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f57782031f48684d8ced235eedfc7d0ef4aa61f4fb564f18a719c9943e87c5f7
+  data.tar.gz: a088814a8dd90650093ead0977269665b98fe7f4a0e5d35705d50892524df0ea
+SHA512:
+  metadata.gz: f73f76a32be50debafc06cada395d5a81a83ca6e85c106ef27b6419ce7ecc4e82c7313157f77c0408fa98115c76906046f13cfd6cee7ecba339cc51c5dac2fda
+  data.tar.gz: bdada82c330195ac1e57cac2e256021074f218d9aa439d1e77bd25d51b84bf7eb137bfe8424b08d3c8d85405d2cd88117bf36058451f075ed9bd484fbc5365d4

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (12 Nov, 2026)
+
+- First version of the Ruby SDK for the Oushodh API `/v1`.
+- `Oushodh::Client`: `meta`, `list_medicines`, `medicines` (an `Enumerator` that pages to the end), `search`,
+  `get_medicine`, `image_url` and `get_image`.
+- Models for `Medicine`, `MedicineDetail`, `Monograph`, `Page`, `SearchResult` and `Meta`, with a reader per field.
+  Unknown fields are kept.
+- Errors by family under `Oushodh::Error`, each with `status`, `code` and `message`.
+- Retries on `429 rate_limited` (honours `Retry-After`), `5xx` and network errors. `429 quota_exceeded` is raised at
+  once.
+- No runtime dependencies.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oushodh
+
+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

@@ -0,0 +1,367 @@
+# Oushodh for Ruby
+
+[![CI](https://github.com/oushodh/oushodh-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/oushodh/oushodh-ruby/actions/workflows/ci.yml)
+
+The official Ruby SDK for the [Oushodh](https://oushodh.dev) medicine data API. Oushodh gives you medicine data for
+Bangladesh, checked against the DGDA register: brands, generics, strengths, dosage forms, manufacturers, MRPs,
+pictures and medical text.
+
+- Ruby 3.3 or newer.
+- No runtime dependencies. It uses `net/http` and `json` from the standard library.
+- One client, `Oushodh::Client`, with typed models, errors by family, retries and an `Enumerator` that pages for you.
+
+The full API reference is at [oushodh.dev/docs](https://oushodh.dev/docs).
+
+## Contents
+
+- [Install](#install)
+- [Get an API key](#get-an-api-key)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Methods](#methods)
+- [Models](#models)
+- [Paging](#paging)
+- [Sync](#sync)
+- [Errors](#errors)
+- [Retries and rate limits](#retries-and-rate-limits)
+- [Plan limits](#plan-limits)
+- [Images](#images)
+- [Develop](#develop)
+- [Release](#release)
+- [License](#license)
+
+## Install
+
+Install from GitHub. Add this line to your `Gemfile`:
+
+```ruby
+gem "oushodh", git: "https://github.com/oushodh/oushodh-ruby.git", tag: "v0.1.0"
+```
+
+Then run `bundle install`.
+
+To pin a commit, add `ref:`:
+
+```ruby
+gem "oushodh", git: "https://github.com/oushodh/oushodh-ruby.git", ref: "<commit sha>"
+```
+
+RubyGems: coming soon (`gem install oushodh`).
+
+## Get an API key
+
+Make a key on the Keys page at [app.oushodh.dev](https://app.oushodh.dev). A key starts with `oush_` and is shown
+once, so copy it then. Keep it on your server: a key inside an app can be copied out of it.
+
+The client reads the key from `api_key:`, or from the `OUSHODH_API_KEY` environment variable when you pass none.
+
+## Quick start
+
+```ruby
+require "oushodh"
+
+client = Oushodh::Client.new # reads OUSHODH_API_KEY
+
+result = client.search("napa 500", limit: 5)
+
+result.items.each do |medicine|
+  puts [medicine.id, medicine.product_name, medicine.prices.strip&.amount].join(" ")
+end
+
+detail = client.get_medicine("MED-012933")
+puts detail.monograph&.indications
+```
+
+## Configuration
+
+```ruby
+client = Oushodh::Client.new(
+  api_key: "oush_...",
+  base_url: "https://api.oushodh.dev",
+  timeout: 30,
+  max_retries: 2
+)
+```
+
+| Option         | Default                   | What it does                                                                        |
+| -------------- | ------------------------- | ----------------------------------------------------------------------------------- |
+| `api_key:`     | `OUSHODH_API_KEY`         | Your API key. With no key at all, `Client.new` raises `Oushodh::Error`.             |
+| `base_url:`    | `https://api.oushodh.dev` | Where the API is.                                                                   |
+| `timeout:`     | `30`                      | Seconds to wait for each request.                                                   |
+| `max_retries:` | `2`                       | Retries after a `429 rate_limited`, a `5xx` or a network error. `0` turns them off. |
+| `transport:`   | `Oushodh::Transport.new`  | Sends the requests, on `Net::HTTP`. Pass your own, for example in tests.            |
+
+A transport is any object with `get(uri, headers:, timeout:)` that returns an `Oushodh::Response` (`status`,
+`headers` with lower-case names, `body`). It raises `Oushodh::ConnectionError` or `Oushodh::TimeoutError` when no
+answer comes back.
+
+```ruby
+class FakeTransport
+  def get(uri, headers:, timeout:)
+    Oushodh::Response.new(status: 200, headers: {}, body: '{"client":"test"}')
+  end
+end
+
+client = Oushodh::Client.new(api_key: "oush_test_123", transport: FakeTransport.new)
+client.meta.client # => "test"
+```
+
+The client never prints your key: `inspect` and `to_s` leave it out, and no error message holds it.
+
+## Methods
+
+| Method                                                | Route                          | Returns                                   |
+| ----------------------------------------------------- | ------------------------------ | ----------------------------------------- |
+| `meta`                                                | `GET /v1/meta`                 | `Meta`                                    |
+| `list_medicines(limit:, cursor:, updated_since:, q:)` | `GET /v1/medicines`            | `Page`                                    |
+| `medicines(limit:, updated_since:, q:)`               | `GET /v1/medicines`, each page | an `Enumerator` of `Medicine`             |
+| `search(q, limit:)`                                   | `GET /v1/medicines/search`     | `SearchResult`                            |
+| `get_medicine(ref)`                                   | `GET /v1/medicines/{ref}`      | `MedicineDetail`                          |
+| `image_url(file)`                                     | none                           | the picture's address, as a `String`      |
+| `get_image(file)`                                     | `GET /v1/images/{file}`        | the picture's bytes, as a binary `String` |
+
+Every keyword is optional.
+
+### meta
+
+The account your key belongs to. Call it to check that the key works.
+
+```ruby
+meta = client.meta
+
+meta.client      # the account the key belongs to
+meta.id_profile  # the ID profile your medicine IDs come from
+meta.medicines   # how many medicines your key reads
+meta.last_import # when the data was last imported, such as "2026-11-09T15:27:40Z"
+```
+
+### list_medicines
+
+One page of medicines. `limit:` is 1 to 500 (default 100). `q:` filters by name, and `updated_since:` keeps only
+medicines changed at or after a time.
+
+```ruby
+page = client.list_medicines(limit: 100, q: "paracetamol")
+
+page.items.size # up to 100
+page.total      # every match, across all pages
+page.next       # pass it back as cursor:, or nil on the last page
+
+following = client.list_medicines(limit: 100, q: "paracetamol", cursor: page.next)
+```
+
+### medicines
+
+Every medicine, page after page to the end. See [Paging](#paging).
+
+```ruby
+client.medicines(q: "napa").each { |medicine| puts medicine.product_name }
+```
+
+### search
+
+The best matches for what a person typed, best match first. `limit:` is 1 to 50 (default 20). When `q` is an ID or a
+UUID, the answer is that one medicine.
+
+```ruby
+result = client.search("napa", limit: 10)
+
+result.items.first&.product_name
+result.total # every match, including those past limit
+```
+
+Search has no cursor. To page every match, use `medicines(q: ...)`.
+
+### get_medicine
+
+One medicine with its medical text. `ref` is a medicine's ID in any profile, an old ID, or its UUID. The answer
+always carries the medicine's current ID.
+
+```ruby
+detail = client.get_medicine("01a1ba6f-f4d6-7143-ac84-9376f520eef8")
+
+detail.id # its current ID
+detail.monograph&.dosage
+detail.monograph&.side_effects
+```
+
+`monograph` is `nil` when no source gives medical text.
+
+### image_url and get_image
+
+`image_url` builds a picture's address. `get_image` fetches its bytes. See [Images](#images).
+
+```ruby
+client.image_url("<file>.jpg") # => "https://api.oushodh.dev/v1/images/<file>.jpg"
+client.get_image("<file>.jpg") # => the picture's bytes
+```
+
+## Models
+
+`Meta`, `Page`, `SearchResult`, `Medicine`, `MedicineDetail`, `Monograph` and `Prices` have a reader for each field
+the API documents, with the API's own names: `medicine.product_name`, `medicine.prices.strip&.amount`, `page.next`.
+A value no source gives is `nil`. Times, such as `last_updated`, stay strings like `2026-11-09T15:27:34Z`. The
+[medicine object](https://oushodh.dev/docs/medicine) page describes every field.
+
+Each model keeps the whole JSON object, so fields the API adds later are kept too. Read them with `[]` or `dig`, or
+get the hash with `to_h`:
+
+```ruby
+medicine["a_new_field"]
+medicine.dig("prices", "currency")
+medicine.to_h
+```
+
+## Paging
+
+`list_medicines` gives one page: `items`, `next` and `total`. Pass `next` back as `cursor:` for the next page. `next`
+is `nil` on the last page.
+
+`medicines` does this for you, page after page to the end. With a block, it yields each medicine. Without one, it
+returns an `Enumerator` that fetches each page only when it needs it:
+
+```ruby
+client.medicines(limit: 500) do |medicine|
+  save(medicine)
+end
+
+first_ten = client.medicines(q: "napa").first(10) # fetches one page
+```
+
+## Sync
+
+Copy the whole database once, then fetch only what changed.
+
+1. The first sync pages through `medicines` to the end. Keep the `last_updated` of the newest medicine.
+2. Each later sync passes that time as `updated_since:` and pages to the end. Medicines come oldest change first.
+
+```ruby
+since = load_last_sync # such as "2026-11-08T09:30:00Z", or nil the first time
+
+client.medicines(limit: 500, updated_since: since).each do |medicine|
+  upsert(medicine.uuid, medicine.to_h)
+  since = [since, medicine.last_updated].compact.max
+end
+
+store_last_sync(since)
+```
+
+`updated_since:` takes a string like `2026-11-08T09:30:00Z`, or a `Time` (or anything with `to_time`). The SDK sends
+a `Time` in UTC to the whole second. It means "at or after", so the medicine that set the time comes back once more.
+Store each medicine by its `uuid`: it never changes. Medicines are never deleted and IDs are never reused.
+
+## Errors
+
+Every error is an `Oushodh::Error`. It has `status` (the HTTP status), `code` (the API's error code) and `message`.
+Match on `code` or on the class, never on `message`: the message is for people and may change. When an error answer
+is not JSON, `code` is `nil` and `message` is `HTTP <status>`.
+
+| Class                            | Status | `code`                             | Retried             |
+| -------------------------------- | ------ | ---------------------------------- | ------------------- |
+| `Oushodh::BadRequestError`       | 400    | `bad_request`                      | no                  |
+| `Oushodh::AuthenticationError`   | 401    | `unauthorized`                     | no                  |
+| `Oushodh::PermissionDeniedError` | 403    | `plan_expired` or `plan_limit`     | no                  |
+| `Oushodh::NotFoundError`         | 404    | `not_found`                        | no                  |
+| `Oushodh::RateLimitError`        | 429    | `rate_limited` or `quota_exceeded` | `rate_limited` only |
+| `Oushodh::InternalServerError`   | 5xx    | `internal`                         | yes                 |
+| `Oushodh::ConnectionError`       | none   | none: the network failed           | yes                 |
+| `Oushodh::TimeoutError`          | none   | none: the request timed out        | yes                 |
+
+`TimeoutError` is a kind of `ConnectionError`. `RateLimitError#retry_after` holds the `Retry-After` seconds.
+
+```ruby
+begin
+  medicine = client.get_medicine("MED-012933")
+rescue Oushodh::NotFoundError
+  medicine = nil
+rescue Oushodh::PermissionDeniedError => e
+  warn "Upgrade your plan to read this medicine." if e.code == "plan_limit"
+  raise
+end
+```
+
+## Retries and rate limits
+
+Every route is a `GET`, so the SDK can safely try again. It retries up to `max_retries` times (default 2):
+
+- `429 rate_limited`: it waits the seconds in the `Retry-After` header, then tries again.
+- `5xx` and network errors: it waits a little longer each time, with jitter.
+- Any other `4xx`: it never retries. They give the same answer every time.
+
+Your plan sets how many requests each key may make in a minute (60 a minute on Developer). Over that limit, the API
+answers `429 rate_limited` with a `Retry-After` header.
+
+Your plan also sets how many requests your account may make in a month. When they are used up, the API answers
+`429 quota_exceeded` until the next month. The SDK raises it at once and never waits. Its `retry_after` holds the
+seconds to the next month.
+
+```ruby
+begin
+  client.meta
+rescue Oushodh::RateLimitError => e
+  raise unless e.code == "quota_exceeded"
+
+  warn "Monthly quota used up. It resets in #{e.retry_after.to_i} seconds."
+end
+```
+
+## Plan limits
+
+Some plans read only the first medicines, in the order of their permanent number. Lists and search leave out the rest.
+A lookup by ID of such a medicine raises `Oushodh::PermissionDeniedError` with `code` `plan_limit`. An expired plan
+gives `code` `plan_expired`. `client.meta.medicines` says how many medicines your key reads.
+
+## Images
+
+`product_image` is the address of a medicine's picture. When it is under `/v1/images/`, Oushodh keeps the copy and
+serves it with no key, so an `<img>` tag can show it. The file never changes, so it can be cached for a year.
+
+`image_url(file)` builds that address. `get_image(file)` fetches the bytes and sends no key. Both take the file name,
+not the whole address, and escape it.
+
+```ruby
+url = medicine.product_image
+
+if url&.start_with?(client.image_url(""))
+  jpeg = client.get_image(url.split("/").last)
+  File.binwrite("#{medicine.uuid}.jpg", jpeg)
+end
+```
+
+Any other address belongs to the source, and it can move or be removed.
+
+## Develop
+
+```sh
+bundle install
+bundle exec rake # RuboCop, then the tests
+```
+
+The tests use a local WEBrick server and fake keys. They never call the API.
+
+| Path                    | What it holds                                           |
+| ----------------------- | ------------------------------------------------------- |
+| `lib/oushodh.rb`        | Loads the whole SDK: `require "oushodh"`.               |
+| `lib/oushodh/client.rb` | `Oushodh::Client`, one method per route.                |
+| `lib/oushodh/models/`   | One file per model, all built on `Oushodh::Model`.      |
+| `lib/oushodh/errors/`   | One file per error class, all under `Oushodh::Error`.   |
+| `lib/oushodh/http/`     | The transport, the `Response` type and the retry rules. |
+
+## Release
+
+For maintainers. The gem is not on RubyGems yet.
+
+1. Set `Oushodh::VERSION` in `lib/oushodh/version.rb` and date the version in `CHANGELOG.md`.
+2. Merge to `main`, then push a tag `v<version>`, such as `v0.1.0`.
+3. The Release workflow checks that the tag matches the version, runs the tests and publishes to RubyGems with
+   trusted publishing. No secret is stored.
+
+## Links
+
+- API docs: [oushodh.dev/docs](https://oushodh.dev/docs)
+- API keys: [app.oushodh.dev](https://app.oushodh.dev)
+- Changes: [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/oushodh/client.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Oushodh
+  # The Oushodh API client.
+  #
+  # `api_key` defaults to the OUSHODH_API_KEY environment variable. Pass `transport:` to send requests your own
+  # way, for example a fake one in tests.
+  class Client
+    DEFAULT_BASE_URL = "https://api.oushodh.dev"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 2
+
+    ERRORS = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError
+    }.freeze
+
+    attr_reader :base_url, :timeout, :max_retries
+
+    def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, transport: Transport.new)
+      key = api_key || ENV.fetch("OUSHODH_API_KEY", nil)
+
+      if key.nil? || key.empty?
+        raise Error, "No API key: pass api_key: or set the OUSHODH_API_KEY environment variable"
+      end
+
+      @api_key = key
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+      @max_retries = max_retries
+      @transport = transport
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect}>"
+    end
+
+    alias to_s inspect
+
+    def meta
+      Meta.new(get_json("/v1/meta"))
+    end
+
+    def list_medicines(limit: nil, cursor: nil, updated_since: nil, q: nil)
+      params = { limit: limit, cursor: cursor, updated_since: format_since(updated_since), q: q }
+
+      Page.new(get_json("/v1/medicines", params))
+    end
+
+    # Every medicine, page after page to the end. Without a block it returns an Enumerator that fetches each
+    # page only when it is needed.
+    def medicines(limit: nil, updated_since: nil, q: nil, &block)
+      unless block_given?
+        return enum_for(:medicines, limit: limit, updated_since: updated_since, q: q)
+      end
+
+      cursor = nil
+
+      loop do
+        page = list_medicines(limit: limit, cursor: cursor, updated_since: updated_since, q: q)
+
+        page.items.each(&block)
+        cursor = page.next
+
+        if cursor.nil?
+          break
+        end
+      end
+    end
+
+    def search(query, limit: nil)
+      SearchResult.new(get_json("/v1/medicines/search", { q: query, limit: limit }))
+    end
+
+    def get_medicine(ref)
+      MedicineDetail.new(get_json("/v1/medicines/#{escape(ref)}"))
+    end
+
+    # The address of a picture, as `product_image` gives it. It needs no key.
+    def image_url(file)
+      "#{@base_url}/v1/images/#{escape(file)}"
+    end
+
+    # The picture's bytes, as a binary String. It sends no key.
+    def get_image(file)
+      request("/v1/images/#{escape(file)}", {}, auth: false).body
+    end
+
+    private
+
+    def get_json(path, params = {})
+      JSON.parse(request(path, params, auth: true).body)
+    end
+
+    def request(path, params, auth:)
+      uri = URI("#{@base_url}#{path}")
+      query = params.compact
+
+      unless query.empty?
+        uri.query = URI.encode_www_form(query)
+      end
+
+      attempt = 0
+
+      loop do
+        error = nil
+
+        begin
+          response = @transport.get(uri, headers: headers(auth), timeout: @timeout)
+        rescue ConnectionError => e
+          error = e
+        else
+          if response.status.between?(200, 299)
+            return response
+          end
+
+          error = api_error(response)
+        end
+
+        delay = Retry.delay(error, attempt, @max_retries)
+
+        if delay.nil?
+          raise error
+        end
+
+        sleep(delay)
+        attempt += 1
+      end
+    end
+
+    def headers(auth)
+      headers = { "User-Agent" => "oushodh-ruby/#{VERSION}" }
+
+      if auth
+        headers["Authorization"] = "Bearer #{@api_key}"
+        headers["Accept"] = "application/json"
+      end
+
+      headers
+    end
+
+    def api_error(response)
+      status = response.status
+      code, message = error_detail(response.body)
+      message ||= "HTTP #{status}"
+
+      if status == 429
+        return RateLimitError.new(message, status: status, code: code, retry_after: retry_after(response))
+      end
+
+      kind = ERRORS.fetch(status) { status >= 500 ? InternalServerError : Error }
+
+      kind.new(message, status: status, code: code)
+    end
+
+    def error_detail(body)
+      detail = JSON.parse(body)["error"]
+
+      unless detail.is_a?(Hash)
+        return [nil, nil]
+      end
+
+      code = detail["code"].is_a?(String) ? detail["code"] : nil
+      message = detail["message"].is_a?(String) ? detail["message"] : nil
+
+      [code, message]
+    rescue JSON::ParserError, TypeError, NoMethodError
+      [nil, nil]
+    end
+
+    def retry_after(response)
+      Float(response.headers["retry-after"], exception: false)
+    end
+
+    def format_since(value)
+      if value.nil? || value.is_a?(String)
+        return value
+      end
+
+      value.to_time.getutc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    end
+
+    def escape(part)
+      part.to_s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |char| format("%%%02X", char.ord) }
+    end
+  end
+end

data/lib/oushodh/errors/authentication_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # 401 `unauthorized`: no key, an unknown key or a revoked key.
+  class AuthenticationError < Error; end
+end

data/lib/oushodh/errors/bad_request_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # 400 `bad_request`.
+  class BadRequestError < Error; end
+end

data/lib/oushodh/errors/connection_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # No answer came back: the network failed.
+  class ConnectionError < Error; end
+end

data/lib/oushodh/errors/error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # The base of every error the SDK raises. `status` is the HTTP status and `code` the API's error code.
+  # Both are nil when no answer came back. Match on `code` or the class, never on `message`.
+  class Error < StandardError
+    attr_reader :status, :code
+
+    def initialize(message, status: nil, code: nil)
+      super(message)
+      @status = status
+      @code = code
+    end
+  end
+end

data/lib/oushodh/errors/internal_server_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # 5xx, such as `internal`.
+  class InternalServerError < Error; end
+end

data/lib/oushodh/errors/not_found_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # 404 `not_found`.
+  class NotFoundError < Error; end
+end

data/lib/oushodh/errors/permission_denied_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # 403 `plan_expired` or `plan_limit`.
+  class PermissionDeniedError < Error; end
+end

data/lib/oushodh/errors/rate_limit_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # 429 `rate_limited` or `quota_exceeded`. `retry_after` is in seconds.
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message, status: nil, code: nil, retry_after: nil)
+      super(message, status: status, code: code)
+      @retry_after = retry_after
+    end
+  end
+end

data/lib/oushodh/errors/timeout_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # No answer came back in time.
+  class TimeoutError < ConnectionError; end
+end

data/lib/oushodh/http/response.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # What a transport answers: the HTTP status, the headers with lower-case names, and the body.
+  Response = Data.define(:status, :headers, :body)
+end

data/lib/oushodh/http/retry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # When to try a failed request again, and how long to wait first.
+  module Retry
+    module_function
+
+    # Seconds to wait before the next try, or nil to raise the error now.
+    def delay(error, attempt, max_retries)
+      if attempt >= max_retries
+        return nil
+      end
+
+      # quota_exceeded waits until next month, so only rate_limited is retried.
+      if error.is_a?(RateLimitError)
+        return error.code == "rate_limited" ? error.retry_after || backoff(attempt) : nil
+      end
+
+      if error.is_a?(InternalServerError) || error.is_a?(ConnectionError)
+        return backoff(attempt)
+      end
+
+      nil
+    end
+
+    def backoff(attempt)
+      [0.5 * (2**attempt), 8.0].min * rand(0.5..1.0)
+    end
+  end
+end

data/lib/oushodh/http/transport.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+
+module Oushodh
+  # The default transport, on Net::HTTP. A transport is any object with `get(uri, headers:, timeout:)` that
+  # returns a Response, or raises ConnectionError or TimeoutError when no answer comes back.
+  class Transport
+    def get(uri, headers:, timeout:)
+      http = Net::HTTP.new(uri.host, uri.port)
+
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      http.max_retries = 0 # the client does its own retries
+
+      response = http.start { |connection| connection.get(uri.request_uri, headers) }
+
+      Response.new(status: response.code.to_i, headers: response.to_hash.transform_values(&:first),
+                   body: response.body || "")
+    rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+      raise TimeoutError, "The request timed out"
+    rescue IOError, SystemCallError, SocketError, OpenSSL::SSL::SSLError, Net::HTTPBadResponse => e
+      raise ConnectionError, "Could not reach the API: #{e.class}"
+    end
+  end
+end

data/lib/oushodh/models/medicine.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # One medicine: one brand in one strength and dosage form.
+  class Medicine < Model
+    fields :id, :uuid, :brand, :category, :product_name, :product_image, :images, :unit, :size, :price,
+           :price_per, :price_source, :description_en, :description_bn, :dosage_form, :strength,
+           :generic_name, :manufacturer, :source_url, :last_updated, :dgda_listed, :medicine_type,
+           unit_prices: [UnitPrice], prices: Prices
+  end
+end

data/lib/oushodh/models/medicine_detail.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # One medicine, with its medical text.
+  class MedicineDetail < Medicine
+    fields monograph: Monograph
+  end
+end

data/lib/oushodh/models/meta.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # The account the key belongs to.
+  class Meta < Model
+    fields :client, :id_profile, :medicines, :last_import
+  end
+end

data/lib/oushodh/models/model.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # A JSON object from the API. It keeps the whole parsed hash, so fields the API adds later stay readable
+  # with `[]` and `to_h`. Each documented field also has a reader.
+  class Model
+    def self.fields(*names, **nested)
+      names.each do |name|
+        define_method(name) { @data[name.to_s] }
+      end
+
+      nested.each do |name, type|
+        define_method(name) { Model.wrap(@data[name.to_s], type) }
+      end
+    end
+
+    def self.wrap(value, type)
+      if value.nil?
+        return nil
+      end
+
+      if type.is_a?(Array)
+        return value.map { |item| type.first.new(item) }
+      end
+
+      type.new(value)
+    end
+
+    def initialize(data)
+      @data = data
+    end
+
+    def [](key)
+      @data[key.to_s]
+    end
+
+    def dig(key, *rest)
+      @data.dig(key.to_s, *rest)
+    end
+
+    def to_h
+      @data
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && other.to_h == @data
+    end
+
+    alias eql? ==
+
+    def hash
+      [self.class, @data].hash
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@data.inspect}>"
+    end
+  end
+end

data/lib/oushodh/models/monograph.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # The medical text of a medicine, as its source wrote it.
+  class Monograph < Model
+    fields :source, :indications, :composition, :pharmacology, :dosage, :interactions, :contraindications,
+           :side_effects, :pregnancy_lactation, :precautions, :overdose, :storage
+  end
+end

data/lib/oushodh/models/pack_amount.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # One `prices.packs` entry.
+  class PackAmount < Model
+    fields :amount, :units, :label, :source
+  end
+end

data/lib/oushodh/models/page.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # One page of medicines.
+  class Page < Model
+    fields :next, :total, items: [Medicine]
+  end
+end

data/lib/oushodh/models/prices.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # Every MRP the sources state for a medicine.
+  class Prices < Model
+    fields :currency, unit: UnitAmount, sizes: [SizeAmount], strip: StripAmount, packs: [PackAmount]
+  end
+end

data/lib/oushodh/models/search_result.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # The best matches for a search.
+  class SearchResult < Model
+    fields :total, items: [Medicine]
+  end
+end

data/lib/oushodh/models/size_amount.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # One `prices.sizes` entry.
+  class SizeAmount < Model
+    fields :size, :amount, :source
+  end
+end

data/lib/oushodh/models/strip_amount.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # `prices.strip`.
+  class StripAmount < Model
+    fields :amount, :units, :source
+  end
+end

data/lib/oushodh/models/unit_amount.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # `prices.unit`.
+  class UnitAmount < Model
+    fields :amount, :source
+  end
+end

data/lib/oushodh/models/unit_price.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Oushodh
+  # One `unit_prices` entry.
+  class UnitPrice < Model
+    fields :size, :price
+  end
+end

data/lib/oushodh/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Oushodh
+  VERSION = "0.1.0"
+end

data/lib/oushodh.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "oushodh/version"
+
+require_relative "oushodh/errors/error"
+require_relative "oushodh/errors/bad_request_error"
+require_relative "oushodh/errors/authentication_error"
+require_relative "oushodh/errors/permission_denied_error"
+require_relative "oushodh/errors/not_found_error"
+require_relative "oushodh/errors/rate_limit_error"
+require_relative "oushodh/errors/internal_server_error"
+require_relative "oushodh/errors/connection_error"
+require_relative "oushodh/errors/timeout_error"
+
+require_relative "oushodh/models/model"
+require_relative "oushodh/models/unit_price"
+require_relative "oushodh/models/unit_amount"
+require_relative "oushodh/models/size_amount"
+require_relative "oushodh/models/strip_amount"
+require_relative "oushodh/models/pack_amount"
+require_relative "oushodh/models/prices"
+require_relative "oushodh/models/medicine"
+require_relative "oushodh/models/monograph"
+require_relative "oushodh/models/medicine_detail"
+require_relative "oushodh/models/page"
+require_relative "oushodh/models/search_result"
+require_relative "oushodh/models/meta"
+
+require_relative "oushodh/http/response"
+require_relative "oushodh/http/retry"
+require_relative "oushodh/http/transport"
+
+require_relative "oushodh/client"
+
+# The Ruby SDK for the Oushodh medicine data API.
+module Oushodh
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: oushodh
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Oushodh
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Medicine data for Bangladesh, checked against the DGDA register.
+email:
+- support@oushodh.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/oushodh.rb
+- lib/oushodh/client.rb
+- lib/oushodh/errors/authentication_error.rb
+- lib/oushodh/errors/bad_request_error.rb
+- lib/oushodh/errors/connection_error.rb
+- lib/oushodh/errors/error.rb
+- lib/oushodh/errors/internal_server_error.rb
+- lib/oushodh/errors/not_found_error.rb
+- lib/oushodh/errors/permission_denied_error.rb
+- lib/oushodh/errors/rate_limit_error.rb
+- lib/oushodh/errors/timeout_error.rb
+- lib/oushodh/http/response.rb
+- lib/oushodh/http/retry.rb
+- lib/oushodh/http/transport.rb
+- lib/oushodh/models/medicine.rb
+- lib/oushodh/models/medicine_detail.rb
+- lib/oushodh/models/meta.rb
+- lib/oushodh/models/model.rb
+- lib/oushodh/models/monograph.rb
+- lib/oushodh/models/pack_amount.rb
+- lib/oushodh/models/page.rb
+- lib/oushodh/models/prices.rb
+- lib/oushodh/models/search_result.rb
+- lib/oushodh/models/size_amount.rb
+- lib/oushodh/models/strip_amount.rb
+- lib/oushodh/models/unit_amount.rb
+- lib/oushodh/models/unit_price.rb
+- lib/oushodh/version.rb
+homepage: https://oushodh.dev/docs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://oushodh.dev/docs
+  source_code_uri: https://github.com/oushodh/oushodh-ruby
+  changelog_uri: https://github.com/oushodh/oushodh-ruby/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Ruby SDK for the Oushodh medicine data API.
+test_files: []