ruby_api_pack_active_campaign 0.2.0

data/README.md

@@ -0,0 +1,270 @@
+# Ruby API Pack ActiveCampaign
+
+## Repository Snapshot
+
+| Field | Value |
+|-------|-------|
+| Project team | `project-ruby` |
+| Repository role | ActiveCampaign API client |
+| Package/artifact | `ruby_api_pack_active_campaign` |
+| Current version/status | 0.2.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_active_campaign.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_active_campaign.svg)](https://rubygems.org/gems/ruby_api_pack_active_campaign)
+[![CircleCI](https://img.shields.io/circleci/build/github/phcdevworks/ruby_api_pack_active_campaign/main.svg)](https://circleci.com/gh/phcdevworks/ruby_api_pack_active_campaign)
+[![codecov](https://codecov.io/gh/phcdevworks/ruby_api_pack_active_campaign/graph/badge.svg?token=QatALQbsJ5)](https://codecov.io/gh/phcdevworks/ruby_api_pack_active_campaign)
+[![License](https://img.shields.io/github/license/phcdevworks/ruby_api_pack_active_campaign.svg)](MIT-LICENSE)
+
+`ruby_api_pack_active_campaign` is a Ruby client gem for the ActiveCampaign API.
+It centralizes ActiveCampaign configuration, HTTP connection handling, response
+parsing, and contact-oriented API helpers so Ruby and Rails applications can
+consume ActiveCampaign without duplicating low-level request code.
+
+[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 configuration object, connection
+wrapper, contact API helpers, and specs. Keep those surfaces aligned whenever an
+ActiveCampaign endpoint or request shape changes.
+
+| Layer | Path | Rule |
+| --- | --- | --- |
+| Gem entry point | `lib/ruby_api_pack_active_campaign.rb` | Loads configuration, connection, and API helper surfaces |
+| Configuration | `lib/ruby_api_pack_active_campaign/configuration.rb` | Owns ActiveCampaign base URL and API token settings |
+| Connection wrapper | `lib/ruby_api_pack_active_campaign/connection/ac_connect.rb` | Centralizes HTTParty requests, headers, JSON parsing, and API errors |
+| Contact API helpers | `lib/ruby_api_pack_active_campaign/api/ac_contacts.rb` | Public contact, automation, import, activity, note, and related-resource helpers |
+| Version | `lib/ruby_api_pack_active_campaign/version.rb` | Gem release version |
+| Specs | `spec/` | Contract and regression coverage for configuration, connection, and API helpers |
+
+After behavior changes, run:
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+gem build ruby_api_pack_active_campaign.gemspec
+```
+
+## What This Gem Owns
+
+- ActiveCampaign API configuration through `RubyApiPackActiveCampaign.configure`
+- HTTParty-based GET, POST, PUT, and DELETE request helpers
+- ActiveCampaign contact helper methods under
+  `RubyApiPackActiveCampaign::Api::AcContacts`
+- JSON response parsing and raised errors for unsuccessful API responses
+- RSpec coverage for connection behavior and API helper delegation
+
+## What This Gem Does Not Own
+
+- ActiveCampaign account setup, billing, lists, automations, or dashboard
+  configuration
+- Host application models, persistence, background jobs, or authorization
+- User-facing Rails controllers or UI components
+- Storage of production credentials or API tokens
+- A complete wrapper for every ActiveCampaign endpoint
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem "ruby_api_pack_active_campaign"
+```
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Or install the gem directly:
+
+```bash
+gem install ruby_api_pack_active_campaign
+```
+
+## Configuration
+
+Configure the ActiveCampaign API URL and token before calling API helpers. In a
+Rails application, this typically belongs in an initializer.
+
+```ruby
+# config/initializers/ruby_api_pack_active_campaign.rb
+RubyApiPackActiveCampaign.configure do |config|
+  config.ac_api_url = ENV.fetch("AC_API_URL")
+  config.ac_api_token = ENV.fetch("AC_API_TOKEN")
+end
+```
+
+`ac_api_url` should include the API version path, for example:
+
+```text
+https://youraccountname.api-us1.com/api/3
+```
+
+Do not commit real ActiveCampaign API tokens. Use Rails credentials, encrypted
+environment management, or your deployment platform's secret manager.
+
+## Contact Usage
+
+Require the gem and call contact helpers through
+`RubyApiPackActiveCampaign::Api::AcContacts`.
+
+```ruby
+require "ruby_api_pack_active_campaign"
+
+RubyApiPackActiveCampaign.configure do |config|
+  config.ac_api_url = ENV.fetch("AC_API_URL")
+  config.ac_api_token = ENV.fetch("AC_API_TOKEN")
+end
+
+contacts = RubyApiPackActiveCampaign::Api::AcContacts.contact_list
+contact = RubyApiPackActiveCampaign::Api::AcContacts.contact_by_id(123)
+```
+
+Create or sync contacts by passing request bodies that match ActiveCampaign's
+API contract:
+
+```ruby
+RubyApiPackActiveCampaign::Api::AcContacts.create_contact(
+  contact: {
+    email: "jane@example.com",
+    firstName: "Jane",
+    lastName: "Example"
+  }
+)
+
+RubyApiPackActiveCampaign::Api::AcContacts.sync_contact(
+  contact: {
+    email: "jane@example.com",
+    firstName: "Jane"
+  }
+)
+```
+
+## Public API Helpers
+
+The current public helper surface is contact-focused:
+
+| Method | ActiveCampaign path |
+| --- | --- |
+| `contact_list` | `GET /contacts` |
+| `contact_by_id(contact_id)` | `GET /contacts/:contact_id` |
+| `create_contact(contact_params)` | `POST /contacts` |
+| `sync_contact(contact_params)` | `POST /contact/sync` |
+| `update_contact(contact_id, contact_params)` | `PUT /contacts/:contact_id` |
+| `delete_contact(contact_id)` | `DELETE /contacts/:contact_id` |
+| `update_contact_list_status(contact_list_params)` | `POST /contactLists` |
+| `list_automations(contact_id)` | `GET /contacts/:contact_id/contactAutomations` |
+| `retrieve_contact_score(contact_id)` | `GET /contacts/:contact_id/scoreValues` |
+| `bulk_import_contacts(import_params)` | `POST /import/bulk_import` |
+| `bulk_import_status_list` | `GET /import/bulk_import` |
+| `bulk_import_status_info` | `GET /import/info` |
+| `list_contact_activities` | `GET /activities` |
+| `retrieve_bounce_logs(contact_id)` | `GET /contacts/:contact_id/bounceLogs` |
+| `retrieve_contact_data(contact_id)` | `GET /contacts/:contact_id/contactData` |
+| `retrieve_contact_goals(contact_id)` | `GET /contacts/:contact_id/contactGoals` |
+| `retrieve_contact_list_memberships(contact_id)` | `GET /contacts/:contact_id/contactLists` |
+| `retrieve_contact_logs(contact_id)` | `GET /contacts/:contact_id/contactLogs` |
+| `retrieve_contact_deals(contact_id)` | `GET /contacts/:contact_id/deals` |
+| `retrieve_contact_field_values(contact_id)` | `GET /contacts/:contact_id/fieldValues` |
+| `retrieve_contact_geo_ips(contact_id)` | `GET /contacts/:contact_id/geoIps` |
+| `retrieve_geo_ip_address(geo_address_id)` | `GET /geoIps/:geo_address_id/geoAddress` |
+| `retrieve_contact_notes(contact_id)` | `GET /contacts/:contact_id/notes` |
+| `list_all_notes` | `GET /notes` |
+| `retrieve_contact_organization(contact_id)` | `GET /contacts/:contact_id/organization` |
+| `retrieve_contact_plus_append(contact_id)` | `GET /contacts/:contact_id/plusAppend` |
+| `retrieve_tracking_logs(contact_id)` | `GET /contacts/:contact_id/trackingLogs` |
+| `retrieve_account_contacts(contact_id)` | `GET /contacts/:contact_id/accountContacts` |
+| `retrieve_automation_entry_counts(contact_id)` | `GET /contacts/:contact_id/automationEntryCounts` |
+
+## Error Handling
+
+Successful responses are parsed from JSON and returned as Ruby hashes. Non-2xx
+responses raise an error with the HTTP status and response body. Invalid JSON
+responses raise a parsing error.
+
+Handle these errors at your application boundary so API failures do not expose
+tokens, request bodies, or sensitive contact data in logs.
+
+## 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_active_campaign.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,40 @@
+# Roadmap
+
+This roadmap tracks the direction for `ruby_api_pack_active_campaign` as a Ruby
+client gem for ActiveCampaign. It is planning context, not a release promise.
+
+## Current Focus
+
+- Keep the contact helper surface stable and well tested.
+- Keep ActiveCampaign API credentials centralized through configuration.
+- Keep HTTP request behavior centralized in the connection wrapper.
+- Improve release hygiene for RubyGems publishing.
+
+## Near-Term
+
+- Expand README examples for common Rails initializer usage.
+- Add clearer guidance for ActiveCampaign request payload shapes.
+- Review response and error handling for a typed error class.
+- Confirm supported Ruby versions across CI and gem metadata (gemspec allows
+  `>= 3.0.0`; CI currently tests only 3.1 and 3.3.x).
+- Add specs for any helper methods that are not covered by endpoint-path
+  assertions.
+- Evaluate additional ActiveCampaign resource groups (lists, tags, deals,
+  automations) now that the project is being actively revived — contact
+  workflows are the only resource group implemented today.
+
+## Later
+
+- Consider separate modules for automations, lists, accounts, and notes if the
+  helper surface grows.
+- Add pagination guidance for list endpoints.
+- Add retry, timeout, and instrumentation guidance without exposing sensitive
+  data.
+
+## Out of Scope
+
+- ActiveCampaign dashboard administration
+- Host application data models or persistence
+- User-facing Rails controllers or views
+- Application-specific marketing automation workflows
+- 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,43 @@
+# 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_active_campaign`
+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.
+- Do not expose ActiveCampaign API tokens, production account URLs, contact
+  data, request payloads, or full response bodies in logs or examples.
+- Store API credentials through Rails encrypted credentials, environment
+  variables, or a secure deployment secret manager.
+- Review automated dependency updates and advisories before release.
+- Mock external ActiveCampaign requests in specs instead of recording sensitive
+  production traffic.
+
+## Contact
+
+For non-sensitive security questions, open an issue or discussion in this
+repository.

data/TODO.md

@@ -0,0 +1,31 @@
+# TODO
+
+## Documentation
+
+- [x] Standardize README structure.
+- [x] Add AI operating guides.
+- [x] Standardize community health docs.
+- [x] Add changelog and roadmap.
+- [ ] Add Rails initializer examples for common host app shapes.
+- [ ] Add ActiveCampaign payload examples for common contact workflows.
+- [ ] Add pagination and rate-limit guidance.
+
+## Ruby Gem
+
+- [ ] Review helper naming for long-term compatibility.
+- [ ] Confirm all public helper methods have endpoint-path specs.
+- [ ] Consider a custom error class for API failures.
+- [ ] Consider timeout configuration for HTTParty requests.
+- [x] Review whether `Oj` should be used directly or removed if unused —
+      removed; `lib/` only ever used `JSON.parse`.
+
+## Release
+
+- [ ] Confirm gemspec metadata links point to the repository and changelog.
+- [ ] Document RubyGems release steps.
+- [x] Keep CI, Codecov, and publish workflows aligned with release docs —
+      removed stray `.github/workflows/main.yml` (bundler-gem scaffold
+      targeting a nonexistent `master` branch, duplicated `test.yml`).
+- [ ] Confirm supported Ruby versions in CI match the gemspec — gemspec
+      requires `>= 3.0.0`, but CI only tests 3.1 and 3.3.x; either lower the
+      matrix to include 3.0 or raise `required_ruby_version` to match CI.

data/lib/ruby_api_pack_active_campaign/api/ac_contacts.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'ruby_api_pack_core'
+
+module RubyApiPackActiveCampaign
+  module Api
+    class AcContacts
+      extend RubyApiPackCore::Handlers::ResponseValidator
+
+      ENDPOINT = '/contacts'
+
+      class << self
+        def contact_by_id(contact_id)
+          validate_response(connection(contact_id).api_get, expected_type: :hash)
+        end
+
+        def contact_list
+          validate_response(connection.api_get, expected_type: :hash)['contacts']
+        end
+
+        def create_contact(contact_params)
+          validate_response(connection.api_post(contact_params), expected_type: :hash)
+        end
+
+        def sync_contact(contact_params)
+          validate_response(connection(nil, '/contact/sync').api_post(contact_params), expected_type: :hash)
+        end
+
+        def update_contact(contact_id, contact_params)
+          validate_response(connection(contact_id).api_put(contact_params), expected_type: :hash)
+        end
+
+        def delete_contact(contact_id)
+          validate_response(connection(contact_id).api_delete, expected_type: :hash)
+        end
+
+        def update_contact_list_status(contact_list_params)
+          validate_response(connection(nil, '/contactLists').api_post(contact_list_params), expected_type: :hash)
+        end
+
+        def list_automations(contact_id)
+          validate_response(connection(contact_id, '/contactAutomations').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_score(contact_id)
+          validate_response(connection(contact_id, '/scoreValues').api_get, expected_type: :hash)
+        end
+
+        def bulk_import_contacts(import_params)
+          validate_response(connection(nil, '/import/bulk_import').api_post(import_params), expected_type: :hash)
+        end
+
+        def bulk_import_status_list
+          validate_response(connection(nil, '/import/bulk_import').api_get, expected_type: :hash)
+        end
+
+        def bulk_import_status_info
+          validate_response(connection(nil, '/import/info').api_get, expected_type: :hash)
+        end
+
+        def list_contact_activities
+          validate_response(connection(nil, '/activities').api_get, expected_type: :hash)
+        end
+
+        def retrieve_bounce_logs(contact_id)
+          validate_response(connection(contact_id, '/bounceLogs').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_data(contact_id)
+          validate_response(connection(contact_id, '/contactData').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_goals(contact_id)
+          validate_response(connection(contact_id, '/contactGoals').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_list_memberships(contact_id)
+          validate_response(connection(contact_id, '/contactLists').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_logs(contact_id)
+          validate_response(connection(contact_id, '/contactLogs').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_deals(contact_id)
+          validate_response(connection(contact_id, '/deals').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_field_values(contact_id)
+          validate_response(connection(contact_id, '/fieldValues').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_geo_ips(contact_id)
+          validate_response(connection(contact_id, '/geoIps').api_get, expected_type: :hash)
+        end
+
+        def retrieve_geo_ip_address(geo_address_id)
+          validate_response(
+            Connection::AcConnect.new(
+              RubyApiPackActiveCampaign.configuration.ac_api_url,
+              "/geoIps/#{geo_address_id}/geoAddress"
+            ).api_get,
+            expected_type: :hash
+          )
+        end
+
+        def retrieve_contact_notes(contact_id)
+          validate_response(connection(contact_id, '/notes').api_get, expected_type: :hash)
+        end
+
+        def list_all_notes
+          validate_response(connection(nil, '/notes').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_organization(contact_id)
+          validate_response(connection(contact_id, '/organization').api_get, expected_type: :hash)
+        end
+
+        def retrieve_contact_plus_append(contact_id)
+          validate_response(connection(contact_id, '/plusAppend').api_get, expected_type: :hash)
+        end
+
+        def retrieve_tracking_logs(contact_id)
+          validate_response(connection(contact_id, '/trackingLogs').api_get, expected_type: :hash)
+        end
+
+        def retrieve_account_contacts(contact_id)
+          validate_response(connection(contact_id, '/accountContacts').api_get, expected_type: :hash)
+        end
+
+        def retrieve_automation_entry_counts(contact_id)
+          validate_response(connection(contact_id, '/automationEntryCounts').api_get, expected_type: :hash)
+        end
+
+        private
+
+        def connection(id = nil, suffix = nil)
+          path = id ? "#{ENDPOINT}/#{id}" : ENDPOINT
+          path = "#{path}#{suffix}" if suffix
+          Connection::AcConnect.new(RubyApiPackActiveCampaign.configuration.ac_api_url, path)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_api_pack_active_campaign/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RubyApiPackActiveCampaign
+  class Configuration
+    attr_accessor :ac_api_url, :ac_api_token
+
+    def initialize
+      @ac_api_url = 'https://youraccountname.api-us1.com/api/3'
+      @ac_api_token = nil
+    end
+  end
+end

data/lib/ruby_api_pack_active_campaign/connection/ac_connect.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'ruby_api_pack_core'
+
+module RubyApiPackActiveCampaign
+  module Connection
+    class AcConnect < RubyApiPackCore::Connection::Base
+      private
+
+      def auth_headers
+        { 'Api-Token' => RubyApiPackActiveCampaign.configuration.ac_api_token }
+      end
+    end
+  end
+end

data/lib/ruby_api_pack_active_campaign/version.rb

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

data/lib/ruby_api_pack_active_campaign.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'ruby_api_pack_core'
+
+require_relative 'ruby_api_pack_active_campaign/configuration'
+require_relative 'ruby_api_pack_active_campaign/connection/ac_connect'
+require_relative 'ruby_api_pack_active_campaign/api/ac_contacts'
+
+module RubyApiPackActiveCampaign
+  extend RubyApiPackCore::Configurable
+
+  def self.configuration_class
+    Configuration
+  end
+end

data/ruby_api_pack_active_campaign.code-workspace

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

data/sig/ruby_api_pack_active_campaign.rbs

@@ -0,0 +1,4 @@
+module RubyApiPackActiveCampaign
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end