purple-client 0.1.9.3 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 381595d6be33f7e1f3c7a838182db63d5f157ba3978fa70f99b78c75391a9c06
-  data.tar.gz: 48aa5d67fd40fd4d8c8b1bf482e4e493d69f77dd8d9c8fe7011382a74437806f
+  metadata.gz: 5ec58b7f5f8e255925536cf2a25eb351f3d1750b90c6fbb14afc1da0adff46ef
+  data.tar.gz: 4d5b8472eb6aeaccc49c9271f3bd512abeb82bd6704c33c61702b46c99b09cf2
 SHA512:
-  metadata.gz: '084bbb42e3790b1e291c5f95dc5928ec23acb1d6df597b8471e7f6effb279c08eff9f99281f046bc9e84658ec03cd39c943d8aa4a510fa79397afe0e4240550e'
-  data.tar.gz: cd0c4805e785f1cc92087b12a902fb23c78c90e15c540d52a4cedf78990a9c3cedd2ebfaf6d5583617e6a7c71b40db0fdfc208e8147e1b1eb0f0aad4a1b47ddc
+  metadata.gz: 9facb7ca2fe19250fb571127f3cf9e0b5b13713ad742b11ff10e423b6baba16bca2faddfe72f89811fbbff428ccfa7cc6fbc57f55ad08e4bca643aac7add6a32
+  data.tar.gz: a5d8da246488a4d47982f58703dd37545b722a8b638d9fcdd31e4372e127f9688f1ae77428b4b8a71bc28d19bf8027cfcb250a7f65bf35e505960d01d4fc8918

data/AGENTS.md

@@ -0,0 +1,154 @@
+# LLM Guide for Purple::Client Wrapper Clients
+
+This repository uses **wrapper clients** built on `Purple::Client`. A wrapper client is a thin Ruby class that declaratively describes an API using the DSL (domain, paths, params, responses, and response schemas). The DSL then generates methods that perform HTTP requests and validate/shape responses.
+
+**A wrapper client is NOT:**
+- A generic HTTP client or SDK with its own request/response plumbing.
+- A place for business logic, caching, retries, or complex data transformations.
+- A replacement for application-level services or models.
+
+## Golden path structure
+
+When adding a new wrapper, follow this structure:
+
+1. **Namespace + client class** (module name matches provider/service name)
+2. **`domain`** declaration
+3. **`path` tree** that mirrors API routes
+4. **`params`** and request **`body`** definitions where applicable
+5. **`response`** blocks for expected status codes
+6. **`root_method`** for each callable endpoint
+
+## Naming conventions
+
+- `root_method` should be a **verb/action** (`convert`, `live_rates`, `historical_rates`).
+- Parameter names should mirror the API parameter names. Ruby `snake_case` is fine—document any mapping or normalization if needed.
+
+## Modeling guidelines
+
+- **Query params**
+  ```ruby
+  params do |base:, symbols: nil|
+    { base: base, symbols: symbols }.compact
+  end
+  ```
+
+- **Request bodies**
+  ```ruby
+  params do |currency:, amount:|
+    { currency: currency, amount: amount }
+  end
+  ```
+  The hash returned by `params` becomes the JSON body for POST/PUT/PATCH. Use `body(...)` to describe **response** schemas.
+
+- **Multiple responses**
+  ```ruby
+  response :ok do
+    body(success: Purple::Boolean)
+  end
+
+  response :bad_request do
+    body(error: { code: Integer, info: { type: String, allow_blank: true } })
+  end
+  ```
+
+- **Optional / nullable fields**
+  ```ruby
+  body(
+    message: { type: String, allow_blank: true },
+    provider_id: { type: String, optional: true }
+  )
+  ```
+
+- **Booleans**
+  ```ruby
+  body(success: Purple::Boolean)
+  ```
+
+- **Arrays**
+  ```ruby
+  body(:array_of, id: Integer, name: String)
+  ```
+
+- **Response transformation**
+  ```ruby
+  body(result: Float) { |res| res.result }
+  ```
+
+
+## Organizing wrappers with `draw`
+
+Use `draw` to keep large wrappers readable by splitting DSL declarations into
+smaller files.
+
+```ruby
+# clients/payments/client.rb
+class Payments::Client < Purple::Client
+  domain 'https://api.example.com'
+
+  draw 'paths/invoices'
+  draw 'paths/refunds.rb'
+end
+
+# clients/payments/paths/invoices.rb
+path :invoices do
+  response :ok do
+    body :default
+  end
+
+  root_method :invoices
+end
+```
+
+## DO / DON'T (for LLMs)
+
+**DO**
+- Use the DSL (`domain`, `path`, `params`, `response`, `body`, `root_method`).
+- Describe response schemas explicitly, even if partial.
+- Keep the wrapper thin; add only small response transformations.
+- Validate responses with `body(...)` so downstream callers get consistent types.
+
+**DON'T**
+- Invent a generic HTTP client or bypass the DSL.
+- Add business logic, persistence, or retries inside the wrapper.
+- Skip response validation or return raw JSON when a schema is expected.
+
+## Skeleton wrapper template (copy/paste)
+
+```ruby
+# frozen_string_literal: true
+
+require "purple/client"
+
+module ProviderName
+  class Client < Purple::Client
+    domain "https://api.provider.example"
+
+    path :resource do
+      params do |id:, verbose: nil|
+        { id: id, verbose: verbose }.compact
+      end
+
+      response :ok do
+        body(
+          id: Integer,
+          name: String,
+          active: Purple::Boolean,
+          metadata: {
+            created_at: String,
+            tags: { type: Array, optional: true }
+          }
+        )
+      end
+
+      response :bad_request do
+        body(
+          error: String,
+          message: { type: String, allow_blank: true }
+        )
+      end
+
+      root_method :fetch_resource
+    end
+  end
+end
+```

data/README.md

@@ -2,6 +2,10 @@
 
 Purple::Client is a small DSL that helps you describe HTTP APIs. You define a domain, paths, and response structures, and the library generates handy methods for interacting with your service.
 
+## For AI / agents
+
+See [AGENTS.md](AGENTS.md) for an LLM-focused guide, naming conventions, and a copy-paste wrapper skeleton.
+
 ## Installation
 
 Add the gem to your project:
@@ -347,6 +351,64 @@ end
 MessagesClient.send_message
 ```
 
+### Splitting large wrappers with `draw`
+
+If a wrapper gets too long, you can move parts of the DSL into separate files
+and load them with `draw`.
+
+`draw` resolves paths relative to the file where it is called. If you omit the
+extension, `.rb` is added automatically.
+
+```ruby
+# clients/payments/client.rb
+class Payments::Client < Purple::Client
+  domain 'https://api.example.com'
+
+  draw 'paths/invoices'
+  draw 'paths/refunds.rb'
+end
+
+# clients/payments/paths/invoices.rb
+path :invoices do
+  response :ok do
+    body :default
+  end
+  root_method :invoices
+end
+```
+
+Use `draw` only to organize DSL definitions (`path`, `params`, `response`,
+`root_method`) into smaller files. Keep wrapper behavior declarative and avoid
+adding non-DSL business logic in drawn files.
+
+## How to build a wrapper client (5 steps)
+
+1. **Define a `domain`** for the API host.
+2. **Build the `path` tree** to reflect the API routes.
+3. **Describe inputs** with `params` and request body fields as needed.
+4. **Describe responses** with `response` blocks and `body` schemas.
+5. **Set `root_method`** and add call examples in docs or specs.
+
+Helpful references:
+- [AGENTS.md](AGENTS.md) (LLM wrapper guide + skeleton)
+- [OpenAPI mapping](docs/openapi_mapping.md)
+- [Testing wrappers](docs/testing_wrappers.md)
+- [Real-world example: exchangerate.host](examples/real_world/exchangerate_host/README.md)
+
+## Scaffold a wrapper client
+
+Generate a new wrapper skeleton with the built-in scaffold command:
+
+```bash
+bin/purple-client scaffold PROVIDER_NAME
+```
+
+Use `--force` to overwrite existing files:
+
+```bash
+bin/purple-client scaffold PROVIDER_NAME --force
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then run
@@ -367,4 +429,3 @@ to the [code of conduct](https://github.com/[USERNAME]/purple-client/blob/main/C
 
 The gem is available as open source under the terms of the
 [MIT License](https://opensource.org/licenses/MIT).
-

data/docs/openapi_mapping.md

@@ -0,0 +1,94 @@
+# OpenAPI → Purple::Client DSL Mapping
+
+This guide shows how to translate common OpenAPI concepts into Purple::Client DSL constructs.
+
+## Mapping overview
+
+| OpenAPI concept | Purple::Client DSL |
+| --- | --- |
+| Path + HTTP method | `path :resource, method: :get` (nested paths reflect URL segments) |
+| Query parameters | `params do |...| ... end` |
+| Request body schema | Use `params` to build the request payload (for POST/PUT/PATCH, the hash returned by `params` becomes the JSON body). Use `body(...)` only for response schemas. |
+| Response codes | `response :ok`, `response :bad_request`, `response :unprocessable_entity`, etc. |
+| JSON object schema | `body(field: Type, nested: { ... })` |
+| Arrays | `body(:array_of, id: Integer, name: String)` |
+| Optional fields | `field: { type: String, optional: true }` |
+| Nullable / blank | `field: { type: String, allow_blank: true }` |
+| Boolean | `Purple::Boolean` |
+
+## Worked example
+
+### OpenAPI snippet
+
+```yaml
+paths:
+  /convert:
+    get:
+      parameters:
+        - in: query
+          name: from
+          schema: { type: string }
+          required: true
+        - in: query
+          name: to
+          schema: { type: string }
+          required: true
+        - in: query
+          name: amount
+          schema: { type: number }
+          required: true
+      responses:
+        "200":
+          description: Conversion result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success: { type: boolean }
+                  query:
+                    type: object
+                    properties:
+                      from: { type: string }
+                      to: { type: string }
+                      amount: { type: number }
+                  result: { type: number }
+        "400":
+          description: Bad request
+```
+
+### Purple::Client DSL
+
+```ruby
+class ExampleClient < Purple::Client
+  domain "https://api.example.com"
+
+  path :convert do
+    params do |from:, to:, amount:|
+      { from: from, to: to, amount: amount }
+    end
+
+    response :ok do
+      body(
+        success: Purple::Boolean,
+        query: {
+          from: String,
+          to: String,
+          amount: Float
+        },
+        result: Float
+      )
+    end
+
+    response :bad_request
+
+    root_method :convert
+  end
+end
+```
+
+### Notes
+
+- Query params are produced by `params` (even for GET requests).
+- Use `Purple::Boolean` for booleans, and `allow_blank` for fields that can be `null` or empty.
+- For arrays, use `body(:array_of, ...)` with the element structure.

data/docs/testing_wrappers.md

@@ -0,0 +1,80 @@
+# Testing Wrapper Clients with RSpec + WebMock
+
+This guide shows how to test Purple::Client wrappers using **RSpec** and **WebMock** (no VCR).
+
+## Setup
+
+Add WebMock to your development/test dependencies (already included in this repo's Gemfile):
+
+```ruby
+# Gemfile
+ gem "webmock", "~> 3.0"
+```
+
+In your spec file, require WebMock and stub HTTP calls:
+
+```ruby
+require "spec_helper"
+require "webmock/rspec"
+```
+
+## Example spec
+
+```ruby
+# spec/exchangerate_host/client_spec.rb
+require "spec_helper"
+require "webmock/rspec"
+require "examples/real_world/exchangerate_host/client"
+
+RSpec.describe ExchangerateHost::Client do
+  it "calls the live rates endpoint with query params" do
+    stub_request(:get, "https://api.exchangerate.host/latest")
+      .with(query: { "base" => "USD", "symbols" => "EUR" })
+      .to_return(
+        status: 200,
+        body: {
+          success: true,
+          base: "USD",
+          date: "2024-01-01",
+          rates: { EUR: 0.92 }
+        }.to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+
+    response = described_class.live(base: "USD", symbols: "EUR")
+
+    expect(response.base).to eq("USD")
+    expect(response.rates[:"EUR"]).to eq(0.92)
+  end
+
+  it "validates non-:ok responses" do
+    stub_request(:get, "https://api.exchangerate.host/latest")
+      .with(query: { "base" => "USD" })
+      .to_return(
+        status: 400,
+        body: {
+          success: false,
+          error: { code: 400, type: "invalid_base", info: nil }
+        }.to_json,
+        headers: { "Content-Type" => "application/json" }
+      )
+
+    response = described_class.live(base: "USD")
+
+    expect(response.error[:type]).to eq("invalid_base")
+  end
+end
+```
+
+## What to assert
+
+- **HTTP method + URL + query params** via `stub_request(...).with(...)`.
+- **Response parsing and validation** by asserting fields defined in `body(...)`.
+- **Non-:ok responses** by stubbing other status codes (`:bad_request`, `:unprocessable_entity`).
+- **Optional/blank fields** by stubbing missing or `null` values and ensuring no validation errors.
+
+## Running the tests
+
+```bash
+bundle exec rspec
+```

data/examples/real_world/exchangerate_host/README.md

@@ -0,0 +1,51 @@
+# Exchangerate Host Wrapper Example
+
+This example shows a minimal, realistic wrapper client for [exchangerate.host](https://exchangerate.host) using `Purple::Client`.
+
+It demonstrates:
+- Multiple endpoints (`live`, `historical`, `convert`, `timeframe`)
+- Required and optional params
+- Nested response structures
+- `optional` and `allow_blank`
+- `Purple::Boolean`
+- A small response transformation for `convert`
+
+## Setup
+
+From the repo root:
+
+```bash
+bundle install
+```
+
+## Run locally (optional live calls)
+
+These examples perform live HTTP requests. If you are offline, skip them and rely on the specs.
+
+```bash
+ruby -r "./examples/real_world/exchangerate_host/client" -e "puts ExchangerateHost::Client.live(base: 'USD', symbols: 'EUR').rates[:eur]"
+
+ruby -r "./examples/real_world/exchangerate_host/client" -e "puts ExchangerateHost::Client.historical('2020-01-01', base: 'USD', symbols: 'EUR').rates[:eur]"
+
+ruby -r "./examples/real_world/exchangerate_host/client" -e "puts ExchangerateHost::Client.convert(from: 'USD', to: 'EUR', amount: 10)"
+
+ruby -r "./examples/real_world/exchangerate_host/client" -e "puts ExchangerateHost::Client.timeframe(start_date: '2020-01-01', end_date: '2020-01-05', base: 'USD').rates.keys"
+```
+
+## Expected response shapes
+
+```ruby
+ExchangerateHost::Client.live(base: "USD", symbols: "EUR")
+# => #<Purple::Responses::Object ...>
+# response.base #=> "USD"
+# response.rates[:"EUR"] #=> 0.92
+
+ExchangerateHost::Client.historical("2020-01-01", base: "USD", symbols: "EUR")
+# => #<Purple::Responses::Object ...>
+
+ExchangerateHost::Client.convert(from: "USD", to: "EUR", amount: 10)
+# => 9.2 (Float)
+
+ExchangerateHost::Client.timeframe(start_date: "2020-01-01", end_date: "2020-01-05", base: "USD")
+# => #<Purple::Responses::Object ...>
+```

data/examples/real_world/exchangerate_host/client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "purple/client"
+
+module ExchangerateHost
+  class Client < Purple::Client
+    domain "https://api.exchangerate.host"
+
+    path :latest do
+      params do |base: "USD", symbols: nil|
+        { base: base, symbols: symbols }.compact
+      end
+
+      response :ok do
+        body(
+          success: Purple::Boolean,
+          base: String,
+          date: String,
+          rates: { type: Hash, allow_blank: true }
+        )
+      end
+
+      response :bad_request do
+        body(
+          success: Purple::Boolean,
+          error: {
+            code: Integer,
+            type: String,
+            info: { type: String, allow_blank: true }
+          }
+        )
+      end
+
+      root_method :live
+    end
+
+    path :historical do
+      path :date, is_param: true do
+        params do |base: nil, symbols: nil|
+          { base: base, symbols: symbols }.compact
+        end
+
+        response :ok do
+          body(
+            success: Purple::Boolean,
+            base: String,
+            date: String,
+            rates: { type: Hash, allow_blank: true }
+          )
+        end
+
+        response :bad_request do
+          body(
+            success: Purple::Boolean,
+            error: {
+              code: Integer,
+              type: String,
+              info: { type: String, allow_blank: true }
+            }
+          )
+        end
+
+        root_method :historical
+      end
+    end
+
+    path :convert do
+      params do |from:, to:, amount:|
+        { from: from, to: to, amount: amount }
+      end
+
+      response :ok do
+        body(
+          success: Purple::Boolean,
+          query: {
+            from: String,
+            to: String,
+            amount: Float
+          },
+          info: {
+            rate: Float,
+            timestamp: { type: Integer, optional: true }
+          },
+          result: Float,
+          date: String
+        ) { |res| res.result }
+      end
+
+      response :unprocessable_entity do
+        body(
+          success: Purple::Boolean,
+          error: {
+            code: Integer,
+            type: String,
+            info: { type: String, allow_blank: true }
+          }
+        )
+      end
+
+      root_method :convert
+    end
+
+    path :timeframe do
+      params do |start_date:, end_date:, base: nil, symbols: nil|
+        {
+          start_date: start_date,
+          end_date: end_date,
+          base: base,
+          symbols: symbols
+        }.compact
+      end
+
+      response :ok do
+        body(
+          success: Purple::Boolean,
+          timeseries: Purple::Boolean,
+          start_date: String,
+          end_date: String,
+          base: String,
+          rates: { type: Hash, allow_blank: true }
+        )
+      end
+
+      response :bad_request do
+        body(
+          success: Purple::Boolean,
+          error: {
+            code: Integer,
+            type: String,
+            info: { type: String, allow_blank: true }
+          }
+        )
+      end
+
+      root_method :timeframe
+    end
+  end
+end

data/lib/purple/client.rb

@@ -69,6 +69,19 @@ module Purple
         @parent_path = path.parent
       end
 
+      def draw(file_path)
+        caller_path = caller_locations(1, 1).first.absolute_path
+        base_dir = File.dirname(caller_path)
+
+        full_path = if File.extname(file_path).empty?
+                      File.expand_path("#{file_path}.rb", base_dir)
+                    else
+                      File.expand_path(file_path, base_dir)
+                    end
+
+        class_eval(File.read(full_path), full_path)
+      end
+
       def root_method(method_name)
         current_path = @parent_path
 

data/lib/purple/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Purple
-  VERSION = "0.1.9.3"
+  VERSION = "0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: purple-client
 version: !ruby/object:Gem::Version
-  version: 0.1.9.3
+  version: '0.2'
 platform: ruby
 authors:
 - Pavel Kalashnikov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-17 00:00:00.000000000 Z
+date: 2026-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-initializer
@@ -61,11 +61,16 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- AGENTS.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/openapi_mapping.md
+- docs/testing_wrappers.md
+- examples/real_world/exchangerate_host/README.md
+- examples/real_world/exchangerate_host/client.rb
 - lib/purple/boolean.rb
 - lib/purple/client.rb
 - lib/purple/client/version.rb