hi_energy_ai 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1e97ca461ca7e385a0230330b8630a893e4715141c294f494c296fda9e3c9c8
-  data.tar.gz: b11f51535e0ea7b9ab64d972c6f8572f02c95c7802556c68505a56dd97cafacb
+  metadata.gz: cd365a1dbbaf333ae14c034bede81b783bad7cb87e0e73abeb7ff184e7bbc2a3
+  data.tar.gz: 945afdd255cbac87336953de997606713a90d9b12de830cf433c3f01de73ed8a
 SHA512:
-  metadata.gz: fcff37287e8139af46061d328a0bab3b89797b628f0b50ccaf409363b7093dd8149b82134117cbba5f928df07ba09f3d2d3ab46426e8d5bf86a40ee1f038f2a2
-  data.tar.gz: c322f67afd5c2330745a94f99a5ad6e68945d1eebe20be245c0f1e72dc937fa23957f850adbfb159efdb225ea678b679d16dc6ec7c98cbfba6a9bb029962363a
+  metadata.gz: e51de8b9891b030bd3e0e122bb3b519401755db2019088e6bdfb1f76e7a6e3bb12d4bd3ae67a1107724b088693b586ac06263e307ce718413200b780b3d1b7f0
+  data.tar.gz: 5daef3ce90013508381bef8a2bb9a6b91aa34c145a082ba023b0da2b8a5a3b4385a097f6b02912397799bd9ec5732f00626a70cba7fca3ace17d8a6360ede0be

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.1.1 — 2026-07-14
+
+### Added
+
+- `HiEnergyAi.new(server_dry_run: true)` and
+  `Configuration#server_dry_run` as the preferred name for the existing
+  `dry_run` option. The old `dry_run:` keyword still works as an alias.
+  Both only set `?dry_run=true` on the request — the server still
+  receives the call and your key must be valid.
+- Mutating resource methods (`create`, `update`, `generate`, `add`) now
+  accept idiomatic kwargs in addition to the positional Hash:
+  `client.contacts.create(email: "x@y.com")` works the same as
+  `client.contacts.create({ email: "x@y.com" })`.
+- `bin/publish` release workflow script.
+- RuboCop linting (`bundle exec rubocop`), a combined `rake` task
+  (specs + lint), an `.rspec` config, and a RuboCop step in CI.
+
+### Changed
+
+- `HiEnergyAi.new` now raises `HiEnergyAi::Error` (with `code: "MISSING_CREDENTIALS"`)
+  instead of `ArgumentError` when neither `api_key` nor `bearer_token` is
+  configured, so a single `rescue HiEnergyAi::Error` catches all SDK
+  failures.
+- Non-JSON error responses (e.g. an HTML 502 from an upstream proxy) are
+  now wrapped as `HiEnergyAi::Error` with the HTTP status and
+  `code: "INVALID_RESPONSE_BODY"` instead of bubbling up a raw
+  `Faraday::ParsingError`.
+- Rewrote the README with a complete Ruby resource reference plus
+  response, pagination, configuration, and error-handling documentation
+  aligned with the current client, and updated repository metadata URLs.
+
+### Removed
+
+- `HiEnergyAi::Resources::Tags#search` (was a silent alias for `#list`).
+  Use `client.tags.list(...)` directly.
+
 ## 0.1.0 — 2026-05-18
 
 ### Added

data/README.md

@@ -26,7 +26,7 @@ Use this gem to integrate Hi Energy AI into Ruby on Rails apps, background jobs,
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [Authentication](#authentication)
-- [API endpoints covered](#api-endpoints-covered)
+- [Ruby resource reference](#ruby-resource-reference)
 - [Affiliate networks and data sources](#affiliate-networks-and-data-sources)
 - [MCP and AI agent integration](#mcp-and-ai-agent-integration)
 - [Pagination, dry run, and rate limits](#pagination-dry-run-and-rate-limits)
@@ -144,35 +144,57 @@ Get your key: [API Documentation → API Key](https://app.hienergy.ai/api_docume
 
 ---
 
-## API endpoints covered
-
-Every method maps to the [API playground](https://app.hienergy.ai/api_documentation):
-
-| Ruby client | HTTP | Use case |
-|-------------|------|----------|
-| `search` | `GET /api/v1/search` | Universal Searchkick search |
-| `deals` | `GET /api/v1/deals` | List and filter affiliate deals / coupons |
-| `advertisers` | `GET /api/v1/advertisers` | Advertiser discovery and filters |
-| `advertisers.search_by_domain` | `GET /api/v1/advertisers/search_by_domain` | Lookup by domain |
-| `advertisers.by_domain` | `GET /api/v1/advertisers?domain=` | Domain filter shorthand |
-| `contacts` | `GET`, `POST /api/v1/contacts` | Contact search and create |
-| `transactions` | `GET /api/v1/transactions` | Affiliate sales and commissions |
-| `clicks` | `GET /api/v1/clicks` | Click-level reporting (date range required) |
-| `opportunities` | `GET /api/v1/opportunities` | Publisher opportunity advertisers |
-| `verticals` | `GET /api/v1/verticals` | Industry / category list |
-| `tags` | `GET /api/v1/tags` | Tag search and tagged advertisers |
-| `publishers` | CRUD `/api/v1/publishers` | Publisher accounts and credentials |
-| `agencies` | `GET /api/v1/agencies` | Agency directory |
-| `networks` | `GET /api/v1/networks` | Affiliate network list |
-| `reports` | `GET /api/v1/reports` | Prebuilt analytics reports |
-| `users` | `/api/v1/users` | Scoped user management |
-| `status_changes` | `GET /api/v1/status_changes` | Advertiser approval history |
-| `deeplinks` | `POST /api/v1/deeplinks/generate` | Tracking link generator |
-| `domains` | `GET /api/v1/domains/search` | Domain search |
-| `tools` | `GET /api/v1/tools` | MCP tool catalog (JSON Schema) |
-| `schema` | `GET /api/v1/schema` | OpenAPI 3.0 download |
-| `exports` | `/api/v1/exports` | Async report exports |
-| `mcp` | `GET`, `POST /mcp` | MCP bootstrap and JSON-RPC |
+## Ruby resource reference
+
+All optional keyword arguments are sent as query parameters. Methods that accept
+`attributes` send JSON request bodies.
+
+| Resource | Methods |
+|----------|---------|
+| `client.search` | `query(q:, **params)` |
+| `client.advertisers` | `list`, `find(id)`, `search_by_domain(domain:)`, `by_domain(domain:)`, `contacts(id)`, `similar(id)`, `related(id)`, `find_more_contacts(id)` |
+| `client.deals` | `list`, `find(id)`, `types`, `translate(id)` |
+| `client.contacts` | `list`, `create(attributes)`, `add(attributes)` |
+| `client.transactions` | `list`, `find(id)` |
+| `client.clicks` | `list(start_date:, end_date:, **params)` |
+| `client.opportunities` | `list` |
+| `client.reports` | `list`, `find(id)` |
+| `client.publishers` | `list`, `find(id)`, `create(attributes)`, `update(id, attributes)`, `find_linkedin_users(id)` |
+| `client.agencies` | `list`, `find(id)` |
+| `client.networks` | `list`, `find(id)` |
+| `client.status_changes` | `list` |
+| `client.tags` | `list`, `advertisers(id)` |
+| `client.users` | `list`, `find(id)`, `create(attributes)`, `update(id, attributes)`, `resend_invitation(id)`, `rotate_api_key(id)` |
+| `client.verticals` | `list` |
+| `client.domains` | `search(domain:)` |
+| `client.deeplinks` | `generate(attributes)` |
+| `client.exports` | `list`, `find(id)`, `create(attributes)` |
+| `client.tools` | `list` |
+| `client.schema` | `fetch` |
+| `client.mcp` | `bootstrap`, `integration`, `initialize_session`, `call(method, params: {})` |
+
+Examples:
+
+```ruby
+client.advertisers.search_by_domain(domain: "example.com", limit: 10)
+client.clicks.list(start_date: "2026-07-01", end_date: "2026-07-13")
+
+# Mutating methods accept idiomatic keyword arguments...
+client.publishers.create(name: "Example Publisher", website: "https://example.com")
+client.deeplinks.generate(url: "https://merchant.example/product")
+
+# ...or a positional Hash (equivalent, useful for dynamic payloads):
+client.publishers.create({ name: "Example Publisher", website: "https://example.com" })
+```
+
+For endpoint-specific filters and request attributes, use the
+[API playground](https://app.hienergy.ai/api_documentation) or fetch the
+current OpenAPI document:
+
+```ruby
+openapi = client.schema.fetch
+openapi.body
+```
 
 ---
 
@@ -222,11 +244,31 @@ client.paginate("/deals", params: { limit: 50 }).each do |page|
 end
 ```
 
+Every successful request returns a `HiEnergyAi::Response`:
+
+```ruby
+response = client.deals.list(limit: 10)
+
+response.success? # true for HTTP 2xx
+response.status   # HTTP status
+response.headers  # response headers
+response.body     # complete parsed JSON
+response.data     # the top-level "data" value
+response.meta     # the top-level "meta" value
+response.to_h     # normalized response hash
+```
+
 ### Dry run
 
-Test integration wiring without live data:
+Add `?dry_run=true` to every request. The server still receives the call and
+your key must be valid — it validates request wiring without treating the call
+as production traffic. `server_dry_run:` is the preferred keyword; `dry_run:`
+remains as an alias.
 
 ```ruby
+HiEnergyAi.new(api_key: key, server_dry_run: true).deals.list(active: true)
+
+# Equivalent (legacy alias):
 HiEnergyAi.new(api_key: key, dry_run: true).deals.list(active: true)
 ```
 
@@ -260,21 +302,54 @@ client = HiEnergyAi.new
 | `app_origin` | `https://app.hienergy.ai` |
 | `timeout` | `30` seconds |
 
+Constructor options override global configuration for one client:
+
+```ruby
+client = HiEnergyAi.new(
+  api_key: ENV.fetch("HI_ENERGY_API_KEY"),
+  timeout: 60,
+  user_agent: "my-app/1.0"
+)
+```
+
+For an endpoint without a resource helper, use the low-level client methods.
+Paths are relative to `base_url`:
+
+```ruby
+client.get("/advertisers", params: { limit: 5 })
+client.post("/exports", body: { report: "transactions" })
+client.patch("/publishers/42", body: { publisher: { name: "New name" } })
+client.delete("/custom_resource/42")
+```
+
 ---
 
 ## Error handling
 
+Every failure — HTTP errors, missing credentials, and unparseable responses —
+raises `HiEnergyAi::Error`, so a single `rescue` catches all SDK failures.
+
 ```ruby
 begin
   client.advertisers.find(999)
 rescue HiEnergyAi::Error => e
-  e.code          # API error code
-  e.message       # Human-readable message
-  e.request_id    # Support / debugging
   e.status        # HTTP status
+  e.code          # API error code
+  e.message       # human-readable message
+  e.request_id    # support/debugging request ID
+  e.details       # optional structured error details
+  e.response_body # parsed or raw response body
 end
 ```
 
+Notable error codes:
+
+| `e.code` | When |
+|----------|------|
+| `MISSING_CREDENTIALS` | `HiEnergyAi.new` was called without `api_key` or `bearer_token` |
+| `INVALID_RESPONSE_BODY` | The server returned a non-JSON body (e.g. an HTML 502 from a proxy) |
+| API-provided codes (`NOT_FOUND`, …) | Returned in the JSON error payload |
+
 ---
 
 ## Frequently asked questions
@@ -290,7 +365,7 @@ This repository is the **official Ruby gem**. Other languages can use the REST A
 ### How do I search advertisers by website domain?
 
 ```ruby
-client.advertisers.by_domain("amazon.com")
+client.advertisers.by_domain(domain: "amazon.com")
 # or
 client.advertisers.search_by_domain(domain: "amazon.com")
 ```
@@ -310,16 +385,28 @@ Sign in at [app.hienergy.ai](https://app.hienergy.ai) and visit [API Documentati
 ```bash
 git clone https://github.com/HiEnergyAgency/hi_energy_api.git
 cd hi_energy_api
-bundle install
-bundle exec rspec
+bin/setup              # install dependencies
+bundle exec rake       # run specs + RuboCop
+```
+
+Individual tasks:
+
+```bash
+bundle exec rspec      # run the test suite
+bundle exec rubocop    # run the linter
+bundle exec rubocop -a # autocorrect safe offenses
+bin/console            # interactive REPL with the gem loaded
 ```
 
-Interactive console:
+To run the checks, build the gem, and publish the current version to RubyGems:
 
 ```bash
-bin/console
+bin/publish
 ```
 
+Publishing requires an authenticated RubyGems account with MFA. Update
+`HiEnergyAi::VERSION` and `CHANGELOG.md` before publishing a new release.
+
 ---
 
 ## Related links

data/lib/hi_energy_ai/client.rb

@@ -17,7 +17,8 @@ module HiEnergyAi
       @configuration ||= Configuration.new
     end
 
-    def initialize(api_key: nil, bearer_token: nil, base_url: nil, app_origin: nil, timeout: nil, user_agent: nil, dry_run: nil)
+    def initialize(api_key: nil, bearer_token: nil, base_url: nil, app_origin: nil, timeout: nil, user_agent: nil,
+                   dry_run: nil, server_dry_run: nil)
       @config = self.class.configuration.dup
       @config.api_key = api_key if api_key
       @config.bearer_token = bearer_token if bearer_token
@@ -25,9 +26,16 @@ module HiEnergyAi
       @config.app_origin = app_origin if app_origin
       @config.timeout = timeout if timeout
       @config.user_agent = user_agent if user_agent
-      @config.dry_run = dry_run unless dry_run.nil?
+      # `server_dry_run` is the preferred name; `dry_run` is kept for
+      # backwards compatibility. Both only set `?dry_run=true` on the
+      # request — the server still receives the call and your key must
+      # be valid. See README "Dry run" for details.
+      effective_dry_run = server_dry_run.nil? ? dry_run : server_dry_run
+      @config.dry_run = effective_dry_run unless effective_dry_run.nil?
 
-      raise ArgumentError, "api_key or bearer_token is required" unless @config.credentials_present?
+      return if @config.credentials_present?
+
+      raise Error.new("api_key or bearer_token is required", code: "MISSING_CREDENTIALS")
     end
 
     def get(path, params: {})
@@ -179,6 +187,22 @@ module HiEnergyAi
       end
 
       handle_response(response)
+    rescue Faraday::ParsingError => e
+      status, raw_body = extract_parsing_error_context(e)
+      message = status ? "API request failed with status #{status}" : "Failed to parse API response"
+      raise Error.new(message, status: status, code: "INVALID_RESPONSE_BODY", response_body: raw_body)
+    end
+
+    def extract_parsing_error_context(error)
+      env = error.response
+      case env
+      when Hash
+        [env[:status], env[:body]]
+      when Faraday::Response
+        [env.status, env.body]
+      else
+        [nil, nil]
+      end
     end
 
     def apply_auth!(req)

data/lib/hi_energy_ai/configuration.rb

@@ -9,6 +9,9 @@ module HiEnergyAi
 
     attr_accessor :api_key, :bearer_token, :base_url, :app_origin, :timeout, :user_agent, :dry_run
 
+    alias server_dry_run dry_run
+    alias server_dry_run= dry_run=
+
     def initialize
       @app_origin = APP_ORIGIN
       @base_url = API_BASE_URL

data/lib/hi_energy_ai/resource.rb

@@ -2,6 +2,8 @@
 
 module HiEnergyAi
   class Resource
+    UNSET = Object.new.freeze
+
     def initialize(client)
       @client = client
     end
@@ -33,5 +35,22 @@ module HiEnergyAi
     def app_post(path, params: {}, body: nil)
       client.app_post(path, params: params, body: body)
     end
+
+    # Used by mutating methods that accept either a positional Hash of
+    # body attributes (legacy) or keyword arguments (idiomatic Ruby).
+    # When a positional hash is given (including an explicit `nil`),
+    # kwargs are treated as query-string params; when the positional
+    # argument is omitted entirely, all kwargs become body attributes.
+    # Reject calls that provide neither, so mutating requests do not
+    # silently send an empty body.
+    def split_attributes(attributes, params)
+      if attributes.equal?(UNSET)
+        raise ArgumentError, "attributes are required" if params.empty?
+
+        [params, {}]
+      else
+        [attributes, params]
+      end
+    end
   end
 end

data/lib/hi_energy_ai/resources/contacts.rb

@@ -7,12 +7,14 @@ module HiEnergyAi
         get("/contacts", params: params)
       end
 
-      def create(attributes, **params)
-        post("/contacts", params: params, body: { contact: attributes })
+      def create(attributes = UNSET, **params)
+        body_attrs, query = split_attributes(attributes, params)
+        post("/contacts", params: query, body: { contact: body_attrs })
       end
 
-      def add(attributes, **params)
-        post("/contacts/add", params: params, body: { contact: attributes })
+      def add(attributes = UNSET, **params)
+        body_attrs, query = split_attributes(attributes, params)
+        post("/contacts/add", params: query, body: { contact: body_attrs })
       end
     end
   end

data/lib/hi_energy_ai/resources/deeplinks.rb

@@ -3,8 +3,9 @@
 module HiEnergyAi
   module Resources
     class Deeplinks < Resource
-      def generate(attributes, **params)
-        post("/deeplinks/generate", params: params, body: attributes)
+      def generate(attributes = UNSET, **params)
+        body_attrs, query = split_attributes(attributes, params)
+        post("/deeplinks/generate", params: query, body: body_attrs)
       end
     end
   end

data/lib/hi_energy_ai/resources/exports.rb

@@ -11,8 +11,9 @@ module HiEnergyAi
         get("/exports/#{id}", params: params)
       end
 
-      def create(attributes, **params)
-        post("/exports", params: params, body: attributes)
+      def create(attributes = UNSET, **params)
+        body_attrs, query = split_attributes(attributes, params)
+        post("/exports", params: query, body: body_attrs)
       end
     end
   end

data/lib/hi_energy_ai/resources/publishers.rb

@@ -11,12 +11,14 @@ module HiEnergyAi
         get("/publishers/#{id}", params: params)
       end
 
-      def create(attributes, **params)
-        post("/publishers", params: params, body: { publisher: attributes })
+      def create(attributes = UNSET, **params)
+        body_attrs, query = split_attributes(attributes, params)
+        post("/publishers", params: query, body: { publisher: body_attrs })
       end
 
-      def update(id, attributes, **params)
-        patch("/publishers/#{id}", params: params, body: { publisher: attributes })
+      def update(id, attributes = UNSET, **params)
+        body_attrs, query = split_attributes(attributes, params)
+        patch("/publishers/#{id}", params: query, body: { publisher: body_attrs })
       end
 
       def find_linkedin_users(id, **params)

data/lib/hi_energy_ai/resources/tags.rb

@@ -7,8 +7,6 @@ module HiEnergyAi
         get("/tags", params: params)
       end
 
-      alias search list
-
       def advertisers(id, **params)
         get("/tags/#{id}/advertisers", params: params)
       end

data/lib/hi_energy_ai/resources/users.rb

@@ -11,12 +11,14 @@ module HiEnergyAi
         get("/users/#{id}", params: params)
       end
 
-      def create(attributes, **params)
-        post("/users", params: params, body: { user: attributes })
+      def create(attributes = UNSET, **params)
+        body_attrs, query = split_attributes(attributes, params)
+        post("/users", params: query, body: { user: body_attrs })
       end
 
-      def update(id, attributes, **params)
-        patch("/users/#{id}", params: params, body: { user: attributes })
+      def update(id, attributes = UNSET, **params)
+        body_attrs, query = split_attributes(attributes, params)
+        patch("/users/#{id}", params: query, body: { user: body_attrs })
       end
 
       def resend_invitation(id, **params)

data/lib/hi_energy_ai/version.rb

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

data/lib/hi_energy_ai.rb

@@ -10,16 +10,16 @@ require_relative "hi_energy_ai/paginator"
 require_relative "hi_energy_ai/resource"
 require_relative "hi_energy_ai/client"
 
-Dir[File.join(__dir__, "hi_energy_ai/resources", "*.rb")].sort.each { |file| require file }
+Dir[File.join(__dir__, "hi_energy_ai/resources", "*.rb")].each { |file| require file }
 
 module HiEnergyAi
   class << self
-    def new(**options)
-      Client.new(**options)
+    def new(**)
+      Client.new(**)
     end
 
-    def configure(&block)
-      Client.configure(&block)
+    def configure(&)
+      Client.configure(&)
     end
 
     def documentation_url

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hi_energy_ai
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Patrick Karsh
@@ -79,6 +79,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement