ruby_api_pack_core 0.1.0

data/README.md

@@ -0,0 +1,281 @@
+# Ruby API Pack Core
+
+## Repository Snapshot
+
+| Field | Value |
+|-------|-------|
+| Project team | `project-ruby` |
+| Repository role | Shared HTTP client foundation for all `ruby_api_pack_*` gems |
+| Package/artifact | `ruby_api_pack_core` |
+| Current version/status | 0.1.0 |
+
+## Standard Workflow
+
+1. Read [AGENTS.md](AGENTS.md), then the agent-specific guide for the task.
+2. Check [TODO.md](TODO.md) and [ROADMAP.md](ROADMAP.md) for current scope.
+3. Make the smallest repo-local change that satisfies the task.
+4. Run `bundle exec rspec`, `bundle exec rubocop`, and
+   `gem build ruby_api_pack_core.gemspec` when validation is required or
+   practical.
+5. Update docs and changelog history only when behavior, public contracts, or
+   release-relevant metadata changed.
+
+## Documentation Map
+
+| Guide | Path |
+|-------|------|
+| Agent rules | [AGENTS.md](AGENTS.md) |
+| Claude Code | [CLAUDE.md](CLAUDE.md) |
+| Codex | [CODEX.md](CODEX.md) |
+| Copilot | [COPILOT.md](COPILOT.md) |
+| Jules | [JULES.md](JULES.md) |
+| Roadmap | [ROADMAP.md](ROADMAP.md) |
+| Todo | [TODO.md](TODO.md) |
+| Changelog | [CHANGELOG.md](CHANGELOG.md) |
+| Security | [SECURITY.md](SECURITY.md) |
+| Code of Conduct | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
+| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
+
+[![Gem Version](https://img.shields.io/gem/v/ruby_api_pack_core.svg)](https://rubygems.org/gems/ruby_api_pack_core)
+[![RSpec](https://github.com/phcdevworks/ruby_api_pack_core/actions/workflows/test.yml/badge.svg)](https://github.com/phcdevworks/ruby_api_pack_core/actions/workflows/test.yml)
+[![License](https://img.shields.io/github/license/phcdevworks/ruby_api_pack_core.svg)](MIT-LICENSE)
+
+`ruby_api_pack_core` is the shared HTTP client foundation consumed by every
+`ruby_api_pack_*` gem (ActiveCampaign, Cloudways, WordPress, and any future
+vendor pack). It owns the connection wrapper's HTTParty/Oj plumbing, a
+generic response-shape validator, and the `configure`/`configuration`
+singleton pattern, so each vendor-specific gem only has to implement its own
+authentication headers, `Configuration` fields, and resource endpoint
+classes — instead of every gem reinventing the same request/response
+boilerplate.
+
+[Contributing](CONTRIBUTING.md) | [Code of Conduct](CODE_OF_CONDUCT.md) |
+[Changelog](CHANGELOG.md) | [Roadmap](ROADMAP.md) |
+[Security Policy](SECURITY.md) | [AI Guide](AGENTS.md)
+
+## Source of Truth
+
+The gem's public behavior is defined by its connection base class, response
+validator, configurable mixin, and specs. Keep those surfaces aligned — every
+`ruby_api_pack_*` gem depends on this contract staying stable.
+
+| Layer | Path | Rule |
+| --- | --- | --- |
+| Gem entry point | `lib/ruby_api_pack_core.rb` | Loads the connection, validator, and configurable surfaces |
+| Connection base | `lib/ruby_api_pack_core/connection/base.rb` | Template-method HTTParty/Oj connection wrapper; subclasses implement `#auth_headers` |
+| Response validator | `lib/ruby_api_pack_core/handlers/response_validator.rb` | Generic `expected_type: :array`/`:hash` response-shape validation |
+| Configurable | `lib/ruby_api_pack_core/configurable.rb` | Shared `configure`/`configuration` singleton mixin |
+| Version | `lib/ruby_api_pack_core/version.rb` | Gem release version |
+| Specs | `spec/` | Contract and regression coverage, exercised against dummy subclasses/modules |
+
+After behavior changes, run:
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+gem build ruby_api_pack_core.gemspec
+```
+
+## What This Gem Owns
+
+- A template-method `RubyApiPackCore::Connection::Base` class providing
+  `api_get`/`api_post`/`api_put`/`api_delete`, URL building, `200..299`
+  status handling, content-type-checked JSON parsing via `Oj`, and
+  descriptive error messages
+- `RubyApiPackCore::Handlers::ResponseValidator`, a generic response-shape
+  validator (`expected_type: :array`/`:hash`) with Rails-aware error logging
+- `RubyApiPackCore::Configurable`, a mixin providing the standard
+  `MyGem.configure { |c| ... }` / `MyGem.configuration` singleton pattern
+- RSpec coverage for all of the above, exercised against synthetic dummy
+  subclasses and modules
+
+## What This Gem Does Not Own
+
+- Any vendor-specific API knowledge — API tokens, OAuth flows, Basic Auth,
+  endpoint paths, or resource classes belong in the consuming
+  `ruby_api_pack_*` gem
+- Host application models, persistence, background jobs, or authorization
+- User-facing Rails controllers or UI components
+- Storage of production credentials or API tokens
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem "ruby_api_pack_core"
+```
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Or install the gem directly:
+
+```bash
+gem install ruby_api_pack_core
+```
+
+In practice, most consumers won't install this gem directly — it's a runtime
+dependency declared by each `ruby_api_pack_*` gem's own gemspec.
+
+## Building a New API Pack on `ruby_api_pack_core`
+
+A new vendor API pack gem needs three pieces built on top of this
+foundation:
+
+### 1. Configuration
+
+```ruby
+module RubyApiPackExample
+  class Configuration
+    attr_accessor :api_url, :api_token
+
+    def initialize
+      @api_url = 'https://api.example.com/v1'
+      @api_token = nil
+    end
+  end
+end
+
+module RubyApiPackExample
+  extend RubyApiPackCore::Configurable
+
+  def self.configuration_class
+    Configuration
+  end
+end
+```
+
+This gives consumers the standard pattern:
+
+```ruby
+RubyApiPackExample.configure do |config|
+  config.api_url = ENV.fetch("EXAMPLE_API_URL")
+  config.api_token = ENV.fetch("EXAMPLE_API_TOKEN")
+end
+```
+
+### 2. Connection wrapper
+
+Subclass `RubyApiPackCore::Connection::Base` and implement only
+`#auth_headers` — everything else (URL building, verb dispatch, status
+handling, JSON parsing) is inherited:
+
+```ruby
+module RubyApiPackExample
+  module Connection
+    class ExampleConnect < RubyApiPackCore::Connection::Base
+      private
+
+      def auth_headers
+        { 'Api-Token' => RubyApiPackExample.configuration.api_token }
+      end
+    end
+  end
+end
+```
+
+### 3. Resource classes
+
+Extend `RubyApiPackCore::Handlers::ResponseValidator` and follow the
+`ENDPOINT` constant + `class << self` + private `connection(id = nil)`
+factory pattern used by every existing `ruby_api_pack_*` resource class:
+
+```ruby
+module RubyApiPackExample
+  module Api
+    class Widgets
+      extend RubyApiPackCore::Handlers::ResponseValidator
+
+      ENDPOINT = '/widgets'
+
+      class << self
+        def widget_list
+          validate_response(connection.api_get, expected_type: :array)
+        end
+
+        def widget_by_id(id)
+          validate_response(connection(id).api_get, expected_type: :hash)
+        end
+
+        private
+
+        def connection(id = nil)
+          path = id ? "#{ENDPOINT}/#{id}" : ENDPOINT
+          Connection::ExampleConnect.new(RubyApiPackExample.configuration.api_url, path)
+        end
+      end
+    end
+  end
+end
+```
+
+This is the same architecture used by `ruby_api_pack_active_campaign`,
+`ruby_api_pack_cloudways`, and `ruby_api_pack_wordpress` — see those gems for
+worked, real-world examples.
+
+## Error Handling
+
+`Connection::Base` raises a plain `RuntimeError` (via `raise "..."`) for
+non-2xx responses, unparseable JSON, or an unexpected content type. This
+matches the existing behavior of every `ruby_api_pack_*` gem. A typed error
+class hierarchy is tracked in [ROADMAP.md](ROADMAP.md) as a future
+enhancement, but is not yet implemented — do not assume specific error
+classes are raised.
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run style checks:
+
+```bash
+bundle exec rubocop
+```
+
+Build the gem locally:
+
+```bash
+gem build ruby_api_pack_core.gemspec
+```
+
+## Documentation and AI Guides
+
+This repository follows the PHCDevworks documentation model used across the
+Spectre and Rails/Ruby workspaces:
+
+- `AGENTS.md` defines shared AI boundaries.
+- `CLAUDE.md`, `CODEX.md`, `COPILOT.md`, and `JULES.md` define agent-specific
+  working rules.
+- `.github/copilot-instructions.md` and `.github/codex-instructions.md` provide
+  GitHub-integrated assistant guidance.
+- `CHANGELOG.md`, `ROADMAP.md`, and `TODO.md` keep release and planning context
+  visible.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, coding standards, pull
+request expectations, and release hygiene.
+
+## Security
+
+Please do not report vulnerabilities through public issues. Follow
+[SECURITY.md](SECURITY.md) for responsible disclosure.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](MIT-LICENSE).

data/ROADMAP.md

@@ -0,0 +1,42 @@
+# Roadmap
+
+This roadmap tracks the direction for `ruby_api_pack_core` as the shared HTTP
+client foundation for every `ruby_api_pack_*` gem. It is planning context, not
+a release promise.
+
+## Current Focus
+
+- Keep `Connection::Base`, `Handlers::ResponseValidator`, and `Configurable`
+  stable now that `ruby_api_pack_active_campaign`, `ruby_api_pack_cloudways`,
+  and `ruby_api_pack_wordpress` all depend on this gem.
+- Keep this gem free of any vendor-specific knowledge.
+
+## Near-Term
+
+- Confirm all three consuming gems pass their own validation gates against
+  the published `ruby_api_pack_core` version.
+- Expand README examples showing how a new `ruby_api_pack_*` gem should
+  subclass `Connection::Base` and extend `Configurable`.
+- Consider a typed error class hierarchy (e.g.
+  `RubyApiPackCore::Errors::HttpError`,
+  `RubyApiPackCore::Errors::ParseError`) shared by all consuming gems, since
+  every gem currently raises plain `RuntimeError`s independently.
+- Confirm supported Ruby versions across CI and gem metadata.
+
+## Later
+
+- Consider an optional retry/backoff hook on `Connection::Base` if more than
+  one consuming gem needs rate-limit handling (currently only
+  `ruby_api_pack_cloudways` retries on rate limits, implemented locally).
+- Add a generator or documented scaffold for creating a new `ruby_api_pack_*`
+  gem from this foundation.
+- Evaluate whether `Handlers::ResponseValidator`'s `expected_key` unwrapping
+  style (used historically by `ruby_api_pack_cloudways`) should be offered as
+  an alternative mode alongside `expected_type`.
+
+## Out of Scope
+
+- Any vendor-specific API knowledge (tokens, endpoint paths, resource classes)
+- Host application data models or persistence
+- User-facing Rails controllers or views
+- Storage or management of production secrets

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+## Supported Versions
+
+PHCDevworks applies security fixes to the current release line of this gem.
+Please use the latest published version of `ruby_api_pack_core` whenever
+possible.
+
+## Reporting a Vulnerability
+
+Do not open a public issue for security problems.
+
+Use GitHub Security Advisories for this repository whenever possible. If that
+is not available, contact the maintainers through GitHub.
+
+Include:
+
+1. A clear description of the issue and its impact
+2. Steps to reproduce or a proof of concept
+3. Affected versions, if known
+4. Any suggested mitigation
+
+## Response Expectations
+
+1. We aim to acknowledge reports within 48 hours.
+2. We aim to provide an initial assessment within 5 business days.
+3. We will coordinate disclosure timing with the reporter when possible.
+
+## Security Guidance
+
+- Keep Ruby, Bundler, HTTParty, and development dependencies up to date.
+- This gem carries no vendor credentials of its own — API tokens, OAuth
+  secrets, and Basic Auth credentials live in the consuming
+  `ruby_api_pack_*` gems' configuration objects, not here.
+- Because every `ruby_api_pack_*` gem depends on this one, a vulnerability
+  here has broader blast radius than a vulnerability in a single vendor pack
+  — treat reports against `Connection::Base` and
+  `Handlers::ResponseValidator` with correspondingly higher urgency.
+- Review automated dependency updates and advisories before release.
+- Specs use synthetic fixtures and mocked HTTParty responses only — never
+  record real vendor API traffic against this repository.
+
+## Contact
+
+For non-sensitive security questions, open an issue or discussion in this
+repository.

data/TODO.md

@@ -0,0 +1,32 @@
+# TODO
+
+## Documentation
+
+- [x] Standardize README structure.
+- [x] Add AI operating guides.
+- [x] Standardize community health docs.
+- [x] Add changelog and roadmap.
+- [ ] Add a worked example of scaffolding a new `ruby_api_pack_*` gem from
+      this foundation.
+
+## Ruby Gem
+
+- [x] Extract shared connection wrapper, response validator, and
+      configurable pattern from `ruby_api_pack_active_campaign`,
+      `ruby_api_pack_cloudways`, and `ruby_api_pack_wordpress`.
+- [ ] Consider a custom error class hierarchy for HTTP and parse failures,
+      shared across all consuming gems.
+- [ ] Consider timeout configuration for HTTParty requests.
+- [ ] Evaluate whether `Handlers::ResponseValidator` should support
+      Cloudways's historical `expected_key` unwrapping mode alongside
+      `expected_type`.
+
+## Requested by Downstream
+
+(none yet)
+
+## Release
+
+- [x] Confirm gemspec metadata links point to the repository and changelog.
+- [x] Document RubyGems release steps.
+- [x] Confirm supported Ruby versions in CI match the gemspec.

data/lib/ruby_api_pack_core/configurable.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module RubyApiPackCore
+  # Extend a top-level gem module with this to get the standard
+  # `MyGem.configure { |c| ... }` / `MyGem.configuration` singleton pattern.
+  #
+  # The extending module must implement `.configuration_class`, returning the
+  # Configuration class to instantiate, e.g.:
+  #
+  #   module MyGem
+  #     extend RubyApiPackCore::Configurable
+  #
+  #     def self.configuration_class
+  #       Configuration
+  #     end
+  #   end
+  module Configurable
+    attr_accessor :configuration
+
+    def configure
+      self.configuration ||= configuration_class.new
+      yield(configuration)
+    end
+  end
+end

data/lib/ruby_api_pack_core/connection/base.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'oj'
+
+module RubyApiPackCore
+  module Connection
+    # Shared HTTParty + Oj request/response plumbing for API pack connection
+    # wrappers. Subclasses provide the vendor-specific piece by implementing
+    # `#auth_headers` (a Hash merged into every request's headers). Everything
+    # else -- URL building, verb dispatch, status handling, JSON parsing, and
+    # error messages -- is identical across packs.
+    class Base
+      attr_reader :api_url_base, :api_path
+
+      def initialize(api_url_base, api_path)
+        @api_url_base = api_url_base
+        @api_path = api_path
+      end
+
+      def api_get(params = {})
+        response = HTTParty.get(
+          full_url,
+          headers: auth_headers,
+          query: params,
+          ssl_version: :TLSv1_2
+        )
+        handle_response(response)
+      end
+
+      def api_post(params = {})
+        response = HTTParty.post(
+          full_url,
+          headers: auth_headers.merge('Content-Type' => 'application/json'),
+          body: params.to_json,
+          ssl_version: :TLSv1_2
+        )
+        handle_response(response)
+      end
+
+      def api_put(params = {})
+        response = HTTParty.put(
+          full_url,
+          headers: auth_headers.merge('Content-Type' => 'application/json'),
+          body: params.to_json,
+          ssl_version: :TLSv1_2
+        )
+        handle_response(response)
+      end
+
+      def api_delete(params = {})
+        response = HTTParty.delete(
+          full_url,
+          headers: auth_headers,
+          query: params,
+          ssl_version: :TLSv1_2
+        )
+        handle_response(response)
+      end
+
+      private
+
+      # Subclasses must implement this, returning a Hash of auth headers
+      # (e.g. an API-token header, an OAuth bearer token, or Basic auth).
+      def auth_headers
+        raise NotImplementedError, "#{self.class} must implement #auth_headers"
+      end
+
+      def full_url
+        "#{@api_url_base}#{@api_path}"
+      end
+
+      def handle_response(response)
+        case response.code
+        when 200..299
+          parse_response(response)
+        else
+          raise "Error: Received status #{response.code} - #{response.body}"
+        end
+      end
+
+      def parse_response(response)
+        return {} if response.body.nil? || response.body.empty?
+
+        content_type = response.headers&.fetch('content-type', nil)
+        raise "Unexpected response: #{response.body}" unless content_type&.include?('application/json')
+
+        Oj.load(response.body, mode: :strict)
+      rescue Oj::ParseError => e
+        raise "Error parsing response: #{e.message}. Raw body: #{response.body}"
+      end
+    end
+  end
+end

data/lib/ruby_api_pack_core/handlers/response_validator.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RubyApiPackCore
+  module Handlers
+    module ResponseValidator
+      def validate_response(response, expected_type: :any)
+        case expected_type
+        when :array
+          raise "Expected an Array, got #{response.class}: #{response.inspect}" unless response.is_a?(Array)
+        when :hash
+          raise "Expected a Hash, got #{response.class}: #{response.inspect}" unless response.is_a?(Hash)
+        end
+
+        response
+      rescue StandardError => e
+        log_error("Error validating response: #{e.message}")
+        raise "An error occurred while processing the response: #{e.message}"
+      end
+
+      private
+
+      def log_error(message)
+        if defined?(Rails)
+          Rails.logger.error(message)
+        else
+          puts "[ERROR] #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_api_pack_core/version.rb

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

data/lib/ruby_api_pack_core.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'oj'
+
+require_relative 'ruby_api_pack_core/version'
+require_relative 'ruby_api_pack_core/configurable'
+require_relative 'ruby_api_pack_core/handlers/response_validator'
+require_relative 'ruby_api_pack_core/connection/base'
+
+module RubyApiPackCore
+end

data/ruby_api_pack_core.code-workspace

@@ -0,0 +1,8 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	],
+	"settings": {}
+}