hi_energy_ai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b1e97ca461ca7e385a0230330b8630a893e4715141c294f494c296fda9e3c9c8
+  data.tar.gz: b11f51535e0ea7b9ab64d972c6f8572f02c95c7802556c68505a56dd97cafacb
+SHA512:
+  metadata.gz: fcff37287e8139af46061d328a0bab3b89797b628f0b50ccaf409363b7093dd8149b82134117cbba5f928df07ba09f3d2d3ab46426e8d5bf86a40ee1f038f2a2
+  data.tar.gz: c322f67afd5c2330745a94f99a5ad6e68945d1eebe20be245c0f1e72dc937fa23957f850adbfb159efdb225ea678b679d16dc6ec7c98cbfba6a9bb029962363a

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 — 2026-05-18
+
+### Added
+
+- Initial RubyGems release
+- Faraday client for Hi Energy AI API v1 (`https://app.hienergy.ai/api/v1`)
+- Resource accessors for advertisers, deals, contacts, transactions, clicks, reports, publishers, search, schema, tools, and more
+- MCP helpers (`GET /mcp`, `POST /mcp` JSON-RPC, `GET /mcp/integration.json`)
+- `HiEnergyAi::Error` with API error codes and `request_id`
+- Offset pagination helpers on `HiEnergyAi::Response`
+- Optional global `dry_run` query parameter support

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Karsh
+
+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,339 @@
+# Hi Energy AI Ruby Gem — Official Affiliate Marketing API Client
+
+[![Gem Version](https://img.shields.io/gem/v/hi_energy_ai)](https://rubygems.org/gems/hi_energy_ai)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.txt)
+[![API Docs](https://img.shields.io/badge/docs-app.hienergy.ai-api_documentation-0d6efd)](https://app.hienergy.ai/api_documentation)
+
+**`hi_energy_ai`** is the official **Ruby client** for the [Hi Energy AI API](https://app.hienergy.ai/api_documentation) — a production REST API for **affiliate marketing data**, **coupon deals**, **advertiser discovery**, **commission transactions**, **click reporting**, and **publisher analytics**.
+
+Use this gem to integrate Hi Energy AI into Ruby on Rails apps, background jobs, data pipelines, AI agents, and MCP-compatible tools without hand-rolling HTTP calls.
+
+| | |
+|---|---|
+| **RubyGems** | [`hi_energy_ai`](https://rubygems.org/gems/hi_energy_ai) |
+| **API base URL** | `https://app.hienergy.ai/api/v1` |
+| **Documentation** | [app.hienergy.ai/api_documentation](https://app.hienergy.ai/api_documentation) |
+| **OpenAPI** | [OpenAPI reference](https://app.hienergy.ai/api_documentation/openapi) |
+| **Repository** | [github.com/HiEnergyAgency/hi_energy_api](https://github.com/HiEnergyAgency/hi_energy_api) |
+
+---
+
+## Table of contents
+
+- [What is the Hi Energy AI API?](#what-is-the-hi-energy-ai-api)
+- [Why use the hi_energy_ai gem?](#why-use-the-hi_energy_ai-gem)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Authentication](#authentication)
+- [API endpoints covered](#api-endpoints-covered)
+- [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)
+- [Configuration](#configuration)
+- [Error handling](#error-handling)
+- [Frequently asked questions](#frequently-asked-questions)
+- [Development](#development)
+- [License](#license)
+
+---
+
+## What is the Hi Energy AI API?
+
+[Hi Energy AI](https://app.hienergy.ai) aggregates and normalizes affiliate program data from major networks — including **FlexOffers**, **Commission Junction (CJ)**, **Rakuten**, **Impact**, **Awin**, **Partnerize**, **Pepperjam**, and **ShareASale** — and exposes it through a single, **AI-friendly JSON API**.
+
+The platform is built for:
+
+- **Affiliate marketers** searching deals and advertisers by domain, category, or keyword
+- **Publishers** tracking transactions, clicks, commissions, and status changes
+- **Developers** building dashboards, ETL jobs, or internal tools on structured JSON
+- **AI agents** using MCP, OpenAPI, and predictable pagination metadata
+
+Full reference: **[Hi Energy AI API Documentation](https://app.hienergy.ai/api_documentation)**
+
+---
+
+## Why use the hi_energy_ai gem?
+
+| Benefit | Description |
+|---------|-------------|
+| **Official client** | Matches the public API playground and OpenAPI schema |
+| **Typed Ruby API** | Resource objects (`client.deals`, `client.advertisers`, …) instead of raw URLs |
+| **Auth built in** | `X-Api-Key` and OAuth bearer support |
+| **Pagination helpers** | Auto-follow `meta.next_page` on list endpoints |
+| **MCP support** | Bootstrap and JSON-RPC against `/mcp` on the app origin |
+| **Dry run mode** | Validate requests with `dry_run=true` without live data |
+| **MIT licensed** | Free to use in commercial Ruby projects |
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "hi_energy_ai"
+```
+
+Or install from RubyGems:
+
+```bash
+gem install hi_energy_ai
+```
+
+**Requirements:** Ruby **3.2+**
+
+---
+
+## Quick start
+
+1. Sign in at [Hi Energy AI](https://app.hienergy.ai) and create an API key on the [API Key page](https://app.hienergy.ai/api_documentation/api_key).
+2. Install the gem and call the API:
+
+```ruby
+require "hi_energy_ai"
+
+client = HiEnergyAi.new(api_key: ENV["HI_ENERGY_API_KEY"])
+
+# Affiliate advertisers
+client.advertisers.list(limit: 5)
+
+# Coupon / promo deals
+client.deals.list(active: true, country: "US")
+
+# Universal search (advertisers, deals, contacts, …)
+client.search.query(q: "nike", types: "advertisers,deals", per_type_limit: 5)
+
+# Commission and sales reports
+client.reports.find("top_advertisers_by_sales", period: "last_90_days", limit: 10)
+```
+
+**Equivalent curl** (same API the gem calls):
+
+```bash
+curl -H "X-Api-Key: YOUR_API_KEY" \
+  "https://app.hienergy.ai/api/v1/advertisers?limit=5"
+```
+
+```bash
+curl -H "X-Api-Key: YOUR_API_KEY" \
+  "https://app.hienergy.ai/api/v1/deals?active=true&country=US"
+```
+
+---
+
+## Authentication
+
+The Hi Energy AI API accepts API keys via header (recommended):
+
+```http
+X-Api-Key: YOUR_API_KEY
+```
+
+```ruby
+client = HiEnergyAi.new(api_key: "your_integration_key")
+```
+
+OAuth **Bearer** tokens for signed-in user sessions:
+
+```ruby
+client = HiEnergyAi.new(bearer_token: ENV["AUTH0_ACCESS_TOKEN"])
+```
+
+Get your key: [API Documentation → API Key](https://app.hienergy.ai/api_documentation/api_key)
+
+---
+
+## 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 |
+
+---
+
+## Affiliate networks and data sources
+
+Hi Energy AI normalizes feeds from:
+
+FlexOffers · CJ (Commission Junction) · Rakuten Advertising · Impact · Awin · Partnerize · Pepperjam · ShareASale · proprietary enrichment
+
+One API key, one JSON schema — no per-network SDK required in Ruby.
+
+---
+
+## MCP and AI agent integration
+
+The API is designed for **AI agents**, **chatbots**, and **MCP clients**. MCP routes run on the app origin (`https://app.hienergy.ai`), not under `/api/v1`:
+
+```ruby
+client.mcp.bootstrap
+client.mcp.integration
+client.mcp.initialize_session
+client.mcp.call("tools/list")
+```
+
+**Initialize MCP via curl:**
+
+```bash
+curl -X POST https://app.hienergy.ai/mcp \
+  -H "X-Api-Key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}'
+```
+
+See also: [MCP Server documentation](https://app.hienergy.ai/api_documentation) · [OpenAPI reference](https://app.hienergy.ai/api_documentation/openapi)
+
+---
+
+## Pagination, dry run, and rate limits
+
+### Pagination
+
+List responses include `data` and `meta` (`current_page`, `next_page`, `per_page`, `has_more`):
+
+```ruby
+client.paginate("/deals", params: { limit: 50 }).each do |page|
+  page.data.each { |deal| process(deal) }
+end
+```
+
+### Dry run
+
+Test integration wiring without live data:
+
+```ruby
+HiEnergyAi.new(api_key: key, dry_run: true).deals.list(active: true)
+```
+
+### Rate limits
+
+| Account type | Limit |
+|--------------|-------|
+| Hi Energy publisher | 1,000 requests / hour |
+| Other publishers | 10,000 requests / hour |
+
+Headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
+
+---
+
+## Configuration
+
+```ruby
+HiEnergyAi.configure do |config|
+  config.api_key = ENV["HI_ENERGY_API_KEY"]
+  config.base_url = HiEnergyAi::Configuration::API_BASE_URL   # https://app.hienergy.ai/api/v1
+  config.app_origin = HiEnergyAi::Configuration::APP_ORIGIN   # https://app.hienergy.ai
+  config.timeout = 60
+end
+
+client = HiEnergyAi.new
+```
+
+| Setting | Default |
+|---------|---------|
+| `base_url` | `https://app.hienergy.ai/api/v1` |
+| `app_origin` | `https://app.hienergy.ai` |
+| `timeout` | `30` seconds |
+
+---
+
+## Error handling
+
+```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
+end
+```
+
+---
+
+## Frequently asked questions
+
+### What is the difference between hi_energy_ai and calling the REST API directly?
+
+The gem wraps the same endpoints documented at [app.hienergy.ai/api_documentation](https://app.hienergy.ai/api_documentation). It adds Ruby resource methods, authentication headers, JSON parsing, pagination iterators, and structured errors — so you do not maintain Faraday or Net::HTTP code in every project.
+
+### Is there a Python or JavaScript SDK?
+
+This repository is the **official Ruby gem**. Other languages can use the REST API or OpenAPI spec at `GET /api/v1/schema`.
+
+### How do I search advertisers by website domain?
+
+```ruby
+client.advertisers.by_domain("amazon.com")
+# or
+client.advertisers.search_by_domain(domain: "amazon.com")
+```
+
+### Does the gem support OpenClaw or custom AI tools?
+
+Yes. Use `client.tools.list` for the MCP tool catalog, `client.schema.fetch` for OpenAPI, and `client.mcp` for JSON-RPC against `/mcp`.
+
+### Where do I get an API key?
+
+Sign in at [app.hienergy.ai](https://app.hienergy.ai) and visit [API Documentation → API Key](https://app.hienergy.ai/api_documentation/api_key).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/HiEnergyAgency/hi_energy_api.git
+cd hi_energy_api
+bundle install
+bundle exec rspec
+```
+
+Interactive console:
+
+```bash
+bin/console
+```
+
+---
+
+## Related links
+
+- [Hi Energy AI API Documentation](https://app.hienergy.ai/api_documentation) — full endpoint reference and playground
+- [OpenAPI / Swagger](https://app.hienergy.ai/api_documentation/openapi)
+- [RubyGems: hi_energy_ai](https://rubygems.org/gems/hi_energy_ai)
+- [GitHub: HiEnergyAgency/hi_energy_api](https://github.com/HiEnergyAgency/hi_energy_api)
+- [CHANGELOG](CHANGELOG.md)
+
+---
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).
+
+API access requires a Hi Energy AI account and API key. Platform terms apply at [app.hienergy.ai](https://app.hienergy.ai).

data/lib/hi_energy_ai/client.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+require "faraday/net_http"
+
+module HiEnergyAi
+  class Client
+    attr_reader :config
+
+    def self.configure
+      yield(configuration)
+      configuration
+    end
+
+    def self.configuration
+      @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)
+      @config = self.class.configuration.dup
+      @config.api_key = api_key if api_key
+      @config.bearer_token = bearer_token if bearer_token
+      @config.base_url = base_url if base_url
+      @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?
+
+      raise ArgumentError, "api_key or bearer_token is required" unless @config.credentials_present?
+    end
+
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    def post(path, params: {}, body: nil)
+      request(:post, path, params: params, body: body)
+    end
+
+    def patch(path, params: {}, body: nil)
+      request(:patch, path, params: params, body: body)
+    end
+
+    def delete(path, params: {})
+      request(:delete, path, params: params)
+    end
+
+    def app_get(path, params: {})
+      app_request(:get, path, params: params)
+    end
+
+    def app_post(path, params: {}, body: nil)
+      app_request(:post, path, params: params, body: body)
+    end
+
+    def request(method, path, params: {}, body: nil)
+      perform_request(api_connection, method, path, params: params, body: body)
+    end
+
+    def app_request(method, path, params: {}, body: nil)
+      perform_request(app_connection, method, path, params: params, body: body)
+    end
+
+    def paginate(path, params: {})
+      Paginator.new(client: self, path: path, params: params)
+    end
+
+    def tools
+      @tools ||= Resources::Tools.new(self)
+    end
+
+    def schema
+      @schema ||= Resources::Schema.new(self)
+    end
+
+    def search
+      @search ||= Resources::Search.new(self)
+    end
+
+    def advertisers
+      @advertisers ||= Resources::Advertisers.new(self)
+    end
+
+    def deals
+      @deals ||= Resources::Deals.new(self)
+    end
+
+    def contacts
+      @contacts ||= Resources::Contacts.new(self)
+    end
+
+    def transactions
+      @transactions ||= Resources::Transactions.new(self)
+    end
+
+    def clicks
+      @clicks ||= Resources::Clicks.new(self)
+    end
+
+    def opportunities
+      @opportunities ||= Resources::Opportunities.new(self)
+    end
+
+    def reports
+      @reports ||= Resources::Reports.new(self)
+    end
+
+    def publishers
+      @publishers ||= Resources::Publishers.new(self)
+    end
+
+    def agencies
+      @agencies ||= Resources::Agencies.new(self)
+    end
+
+    def networks
+      @networks ||= Resources::Networks.new(self)
+    end
+
+    def status_changes
+      @status_changes ||= Resources::StatusChanges.new(self)
+    end
+
+    def tags
+      @tags ||= Resources::Tags.new(self)
+    end
+
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+
+    def verticals
+      @verticals ||= Resources::Verticals.new(self)
+    end
+
+    def domains
+      @domains ||= Resources::Domains.new(self)
+    end
+
+    def deeplinks
+      @deeplinks ||= Resources::Deeplinks.new(self)
+    end
+
+    def exports
+      @exports ||= Resources::Exports.new(self)
+    end
+
+    def mcp
+      @mcp ||= Resources::Mcp.new(self)
+    end
+
+    private
+
+    def api_connection
+      @api_connection ||= build_connection(config.base_url)
+    end
+
+    def app_connection
+      @app_connection ||= build_connection(config.app_origin)
+    end
+
+    def build_connection(base_url)
+      Faraday.new(url: base_url) do |faraday|
+        faraday.request :json
+        faraday.response :json, content_type: /\bjson$/
+        faraday.options.timeout = config.timeout
+        faraday.options.open_timeout = config.timeout
+        faraday.headers["Accept"] = "application/json"
+        faraday.headers["User-Agent"] = config.user_agent
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def perform_request(connection, method, path, params: {}, body: nil)
+      response = connection.run_request(method, normalize_path(path), body, nil) do |req|
+        req.params.update(compact_params(params)) if params.any? || config.dry_run
+        apply_auth!(req)
+      end
+
+      handle_response(response)
+    end
+
+    def apply_auth!(req)
+      if !config.api_key.to_s.empty?
+        req.headers["X-Api-Key"] = config.api_key
+      elsif !config.bearer_token.to_s.empty?
+        req.headers["Authorization"] = "Bearer #{config.bearer_token}"
+      end
+    end
+
+    def normalize_path(path)
+      path.to_s.delete_prefix("/")
+    end
+
+    def compact_params(params)
+      merged = params.each_with_object({}) do |(key, value), memo|
+        next if value.nil?
+
+        memo[key] = value
+      end
+
+      merged[:dry_run] = true if config.dry_run && !merged.key?(:dry_run) && !merged.key?("dry_run")
+      merged
+    end
+
+    def handle_response(response)
+      status = response.status
+      body = normalize_body(response.body)
+
+      return Response.new(status: status, headers: response.headers, body: body) if success_status?(status)
+
+      raise Error.from_response(status, body)
+    end
+
+    def normalize_body(body)
+      return body if body.is_a?(Hash) || body.is_a?(Array)
+      return {} if body.nil? || body.to_s.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def success_status?(status)
+      status >= 200 && status < 300
+    end
+  end
+end

data/lib/hi_energy_ai/configuration.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module HiEnergyAi
+  class Configuration
+    APP_ORIGIN = "https://app.hienergy.ai"
+    API_BASE_URL = "https://app.hienergy.ai/api/v1"
+    DOCUMENTATION_URL = "https://app.hienergy.ai/api_documentation"
+    DEFAULT_TIMEOUT = 30
+
+    attr_accessor :api_key, :bearer_token, :base_url, :app_origin, :timeout, :user_agent, :dry_run
+
+    def initialize
+      @app_origin = APP_ORIGIN
+      @base_url = API_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @dry_run = false
+      @user_agent = "hi_energy_ai/#{HiEnergyAi::VERSION} (Ruby #{RUBY_VERSION})"
+    end
+
+    def credentials_present?
+      !api_key.to_s.empty? || !bearer_token.to_s.empty?
+    end
+  end
+end

data/lib/hi_energy_ai/error.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module HiEnergyAi
+  class Error < StandardError
+    attr_reader :status, :code, :request_id, :details, :response_body
+
+    def initialize(message = nil, status: nil, code: nil, request_id: nil, details: nil, response_body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @details = details
+      @response_body = response_body
+    end
+
+    def self.from_response(status, body)
+      payload = parse_json(body)
+      error = payload.is_a?(Hash) ? payload["error"] || payload[:error] : nil
+
+      if error.is_a?(Hash)
+        new(
+          error["message"] || error[:message] || "API request failed",
+          status: status,
+          code: error["code"] || error[:code],
+          request_id: error["request_id"] || error[:request_id],
+          details: error["details"] || error[:details],
+          response_body: body
+        )
+      else
+        new("API request failed with status #{status}", status: status, response_body: body)
+      end
+    end
+
+    def self.parse_json(body)
+      return body if body.is_a?(Hash) || body.is_a?(Array)
+      return {} if body.nil? || body.to_s.strip.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      {}
+    end
+    private_class_method :parse_json
+  end
+end