ruby_api_pack_core 0.1.0

data/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md - Ruby API Pack Core
+
+## Project Identity
+
+**Gem:** `ruby_api_pack_core`
+**Owner:** PHCDevworks
+**Primary implementation agent:** Claude Code
+
+This repository is a Ruby gem providing the shared HTTP client foundation used
+by every `ruby_api_pack_*` gem (ActiveCampaign, Cloudways, WordPress, and any
+future vendor pack). It owns the connection wrapper's HTTParty/Oj plumbing,
+the response-shape validator, and the `configure`/`configuration` singleton
+pattern, so each vendor-specific gem only implements its own authentication
+headers, `Configuration` fields, and resource endpoint classes. This file is
+the implementation guide for Claude Code. Read `AGENTS.md` first for shared
+agent boundaries.
+
+This gem has no vendor-specific knowledge of any kind — no API tokens, no
+endpoint paths, no resource classes. If a change requires knowing which
+third-party API is being called, it belongs in the consuming
+`ruby_api_pack_*` gem, not here.
+
+## Commit Policy
+
+Claude Code does not create commits in this repository unless explicitly asked.
+Prepare changes, run validation, and leave commit, tag, push, and release
+authority to the human maintainer.
+
+## Development Workflow
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+gem build ruby_api_pack_core.gemspec
+```
+
+## Ruby Gem Contract
+
+The public behavior surface is:
+
+- `lib/ruby_api_pack_core.rb`
+- `lib/ruby_api_pack_core/configurable.rb`
+- `lib/ruby_api_pack_core/connection/base.rb`
+- `lib/ruby_api_pack_core/handlers/response_validator.rb`
+- `README.md`
+
+Connection, validator, configurable, and response behavior changes require
+matching specs and a changelog entry, because every downstream
+`ruby_api_pack_*` gem inherits this behavior directly.
+
+## Implementation Rules
+
+1. Keep this gem free of vendor-specific knowledge — no API tokens, endpoint
+   paths, resource classes, or third-party response shapes.
+2. `RubyApiPackCore::Connection::Base` is a template-method base class.
+   Subclasses in consuming gems must only override `#auth_headers`; do not add
+   vendor-specific public methods to `Base` itself.
+3. Preserve the public method names on `Connection::Base`
+   (`api_get`/`api_post`/`api_put`/`api_delete`) and
+   `Handlers::ResponseValidator` (`validate_response`) unless the change is
+   intentionally breaking — every `ruby_api_pack_*` gem depends on this
+   surface staying stable.
+4. Any breaking change here requires a coordinated migration plan across
+   `ruby_api_pack_active_campaign`, `ruby_api_pack_cloudways`, and
+   `ruby_api_pack_wordpress` before or alongside the release — do not publish
+   a breaking `ruby_api_pack_core` version without updating consumers.
+5. Avoid broad refactors unless they directly support the requested change.
+6. Do not expose credentials, tokens, or vendor response bodies in logs,
+   fixtures, docs, or test output — this gem's specs use synthetic fixtures
+   only, never real API traffic.
+
+## Testing Expectations
+
+- `Connection::Base` changes need GET, POST, PUT, DELETE, parsing, and
+  failure specs, exercised against a dummy subclass (see
+  `spec/ruby_api_pack_core/connection/base_spec.rb`).
+- `Handlers::ResponseValidator` changes need specs for every `expected_type`
+  branch plus the Rails/non-Rails logging paths.
+- `Configurable` changes need specs covering memoization and multiple
+  `configure` calls.
+- Security-sensitive changes should include both success and failure coverage.
+
+## Documentation Expectations
+
+Update:
+
+- `README.md` for public installation, usage, or contract changes.
+- `CHANGELOG.md` for every behavior-impacting change.
+- `SECURITY.md` when security reporting or guidance changes.
+- AI docs when agent workflows or authority boundaries change.
+- The consuming gems' own `CLAUDE.md`/`README.md` if this gem's contract
+  changes in a way that affects how they subclass or extend it.
+
+## Release Procedure
+
+1. Update `lib/ruby_api_pack_core/version.rb`.
+2. Move changelog notes from `[Unreleased]` into a dated version section.
+3. Run `bundle exec rspec`.
+4. Run `bundle exec rubocop`.
+5. Confirm `ruby_api_pack_active_campaign`, `ruby_api_pack_cloudways`, and
+   `ruby_api_pack_wordpress` still pass their own validation gates against the
+   new version before publishing, if the change is anything other than
+   additive.
+6. Build and publish only when the maintainer explicitly approves.

data/CODEX.md

@@ -0,0 +1,66 @@
+# CODEX.md - Ruby API Pack Core
+
+## Role
+
+Codex owns documentation standardization, release readiness, repo hygiene,
+production stabilization, and configuration consistency for this Ruby gem.
+Claude Code leads implementation changes. Human maintainers own final commit,
+merge, tag, publish, and release decisions.
+
+## Default Workflow
+
+1. Inspect the current working tree and preserve unrelated local changes.
+2. Read the relevant source, specs, and docs before editing.
+3. Make focused changes using existing Ruby and RSpec patterns.
+4. Update README, changelog, and AI docs when public guidance changes.
+5. Run `bundle exec rspec` and `bundle exec rubocop` when feasible.
+6. Build with `gem build ruby_api_pack_core.gemspec` when packaging or release
+   metadata changed.
+7. Report any validation that could not be run.
+
+## Documentation Scope
+
+Codex may update:
+
+- `README.md`
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+- `CODE_OF_CONDUCT.md`
+- `CHANGELOG.md`
+- `ROADMAP.md`
+- `TODO.md`
+- `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `COPILOT.md`, `JULES.md`
+- `.github/` templates and assistant instructions
+- `.codex/` workspace notes
+
+## Review Scope
+
+When reviewing changes, Codex checks:
+
+1. `Connection::Base`, `Handlers::ResponseValidator`, and `Configurable`
+   behavior drift.
+2. Missing RSpec coverage for connection, validator, or configurable changes.
+3. Vendor-specific knowledge (API tokens, endpoint paths, resource classes)
+   accidentally introduced into this gem.
+4. Inconsistent response parsing or error behavior.
+5. README or changelog drift from the public behavior surface.
+6. CI and release workflow mismatch with documented commands.
+7. Breaking changes that were not flagged as requiring coordination with
+   `ruby_api_pack_active_campaign`, `ruby_api_pack_cloudways`, and
+   `ruby_api_pack_wordpress`.
+
+## Validation Commands
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+gem build ruby_api_pack_core.gemspec
+```
+
+## Hard Limits
+
+- Do not publish the gem unless explicitly asked.
+- Do not create commits, tags, or releases unless explicitly asked.
+- Do not overwrite unrelated local changes.
+- Do not add vendor-specific knowledge, real credentials, or sensitive
+  payloads to documentation or tests.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+development@phcdevworks.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -0,0 +1,111 @@
+# Contributing to Ruby API Pack Core
+
+Thanks for helping improve `ruby_api_pack_core`. This gem is maintained by
+PHCDevworks as the shared HTTP client foundation for every `ruby_api_pack_*`
+gem — it has no vendor-specific knowledge of its own.
+
+## Development Setup
+
+1. Clone the repository.
+2. Install dependencies with `bundle install`.
+3. Run `bundle exec rspec`.
+4. Run `bundle exec rubocop`.
+5. Build the gem with `gem build ruby_api_pack_core.gemspec` when preparing a
+   release or changing packaging metadata.
+
+## Project Structure
+
+- `lib/ruby_api_pack_core.rb`: public gem entry point
+- `lib/ruby_api_pack_core/configurable.rb`: shared `configure`/`configuration`
+  singleton mixin
+- `lib/ruby_api_pack_core/connection/base.rb`: shared HTTParty/Oj connection
+  template class
+- `lib/ruby_api_pack_core/handlers/response_validator.rb`: shared
+  response-shape validator
+- `lib/ruby_api_pack_core/version.rb`: gem version
+- `spec/`: RSpec coverage for the connection base class, validator, and
+  configurable mixin, tested against synthetic dummy classes
+
+## Contribution Guidelines
+
+### Connection, validator, and configurable changes
+
+1. Keep public method names stable
+   (`api_get`/`api_post`/`api_put`/`api_delete`, `validate_response`,
+   `configure`/`configuration`) unless the change is intentionally breaking.
+2. Add or update focused specs for any behavior change, exercised against a
+   dummy subclass or dummy module — never against a real vendor API.
+3. Keep this gem free of vendor-specific knowledge. If a change requires
+   knowing which third-party API is being called, it belongs in a consuming
+   `ruby_api_pack_*` gem instead.
+4. Any breaking change here must be coordinated with
+   `ruby_api_pack_active_campaign`, `ruby_api_pack_cloudways`, and
+   `ruby_api_pack_wordpress` before or alongside release.
+
+### Code and tooling
+
+- Follow the repo's RuboCop configuration.
+- Prefer small, pattern-aligned changes.
+- Keep comments brief and only add them when they explain a non-obvious reason.
+- Preserve unrelated local changes.
+- Do not create commits, tags, releases, or publish gems unless explicitly
+  asked by a maintainer.
+
+## Behavior-Impacting Change Checklist
+
+Use this checklist when touching any public behavior surface:
+
+- `lib/ruby_api_pack_core.rb`
+- `lib/ruby_api_pack_core/configurable.rb`
+- `lib/ruby_api_pack_core/connection/base.rb`
+- `lib/ruby_api_pack_core/handlers/response_validator.rb`
+- `README.md`
+
+Before merge:
+
+1. Update or add focused specs.
+2. Run `bundle exec rspec`.
+3. Run `bundle exec rubocop`.
+4. Build with `gem build ruby_api_pack_core.gemspec` when packaging metadata
+   changed.
+5. Update `README.md` if installation, usage, or contract guidance changed.
+6. Update `CHANGELOG.md` under `[Unreleased]`.
+7. Classify the change as additive, behavior change, breaking, or docs/config
+   only in the pull request.
+8. If the change is breaking, note the required follow-up in the three
+   consuming gems.
+
+## Pull Request Checklist
+
+1. Keep the change focused.
+2. Fill out every section of `.github/pull_request_template.md`.
+3. Link an issue or write `N/A`.
+4. Include a concise summary and reviewer notes.
+5. Leave blocked checklist items unchecked with a short note.
+
+## Release Hygiene
+
+For maintainers, a release should keep these records aligned:
+
+1. Update `lib/ruby_api_pack_core/version.rb`.
+2. Move relevant `CHANGELOG.md` `[Unreleased]` notes into a dated version entry.
+3. Run `bundle exec rspec`.
+4. Run `bundle exec rubocop`.
+5. Build the gem from the matching source state.
+6. Confirm the three consuming gems still pass their own validation gates
+   against the new version, if the change is anything other than additive.
+7. Publish release notes from the matching changelog entry.
+
+## Questions
+
+Open an issue if you need direction before making a larger change.
+
+## Code of Conduct
+
+By participating in this project, you agree to follow the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+MIT License.

data/COPILOT.md

@@ -0,0 +1,30 @@
+# COPILOT.md - Ruby API Pack Core
+
+## Role
+
+GitHub Copilot is a support assistant for local development in this repository.
+It may help with Ruby, RSpec, documentation, and small refactors, but it does
+not own architecture, release decisions, or final handoff authority.
+
+## Repository Conventions
+
+- Keep HTTParty/Oj plumbing centralized in `Connection::Base`.
+- Keep this gem free of vendor-specific knowledge (API tokens, endpoint paths,
+  resource classes) — that belongs in the consuming `ruby_api_pack_*` gems.
+- Add focused RSpec coverage for behavior changes.
+- Keep README and changelog aligned with public usage.
+- Do not create commits unless explicitly asked.
+
+## Validation
+
+Run these before handing off non-trivial changes:
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Security
+
+Never suggest adding real API tokens, credentials, or vendor response bodies
+to source control. This gem's specs use synthetic fixtures only.

data/JULES.md

@@ -0,0 +1,34 @@
+# JULES.md - Ruby API Pack Core
+
+## Role
+
+Google Jules may perform bounded automated maintenance in this repository.
+Jules should keep work small, mechanical, and easy to review.
+
+## Appropriate Work
+
+- Dependency update follow-ups
+- Small documentation corrections
+- CI or configuration cleanup
+- Narrow test maintenance
+- Formatting updates aligned with RuboCop
+
+## Not Appropriate
+
+- Changes to `Connection::Base`, `Handlers::ResponseValidator`, or
+  `Configurable` public method signatures
+- Public API redesigns
+- Release publishing
+- Large refactors
+- Security-sensitive behavior changes without human review
+
+## Validation
+
+Before handoff, run:
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+If validation cannot run, report why.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Copyright Bradley J Potts
+
+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.