ecoportal-api 0.10.15 → 0.10.17

data/docs/self-docs/OPERATIONS.md

@@ -0,0 +1,64 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api"
+doc: operations
+last_generated: "2026-07-23"
+source_head: "69bf8e3"
+review_status: draft
+---
+
+# Operations -- ecoportal-api
+
+**Purpose:** the infrastructure / exposure / value surface for DevOps and Engineering. It lets ROVO answer
+"what infrastructure is involved, is it behind Cloudflare, what governs its flows, and is it worth it?"
+Same trust rule as COMPLIANCE.md: separate EVIDENCE from INTENT; audit answers use `reviewed` docs only.
+
+## Infrastructure inventory
+
+| Component | Type (compute/store/queue/...) | Where hosted | Notes |
+|---|---|---|---|
+| `ecoportal-api` gem itself | Library (no compute of its own) | Distributed via RubyGems.org; runs inside WHATEVER process requires it (no dedicated compute in this repo) | Not a deployed service -- no `Dockerfile`/`cdk.json`/`docker-compose.yml`/Terraform found in this repo |
+| ecoPortal REST API (`live.ecoportal.com`) | External compute the gem calls as a CLIENT | ecoPortal's own infrastructure -- not this repo's | This repo does not own or operate this API; it only calls it. unknown -- needs owner input on which repo documents that API's own infrastructure |
+| Elastic APM / Elastic Cloud | External SaaS (observability) | Elastic Cloud, `ap-southeast-2` region by default (`elastic_apm_integration.rb`) | Optional, env-var gated, fails open |
+
+## Public exposure
+
+This repo has no publicly reachable domain or endpoint of its own -- it is a Ruby library, not a
+hosted service (no server/Lambda entry point found; see `ARCHITECTURE.md` "Entry points"). It
+makes OUTBOUND calls (as a client) to `live.ecoportal.com` and, optionally, Elastic Cloud.
+
+| Public domain / endpoint | Behind Cloudflare? | Security rules governing the flow |
+|---|---|---|
+| N/A -- no inbound public endpoint in this repo | N/A | N/A |
+
+unknown -- needs owner input on whether `live.ecoportal.com` itself sits behind Cloudflare (that is
+the ecoPortal product API's own infrastructure question, out of scope for this client-gem repo).
+
+## DevOps audit runbook
+
+- Run tests: `bundle install && bundle exec rspec` (`CLAUDE.md`, `README.md`).
+- Run lint: `bundle exec rubocop` (or `bundle exec rake rubocop`, per `Rakefile`).
+- Default task (`rake`, no args): runs RuboCop then RSpec (`Rakefile`).
+- Check installed AI-standards alignment: `.ai-assistance/standards-version.json` (currently
+  `ep-ai-standards-version: 1.9.1`, applied 2026-07-22, installed components
+  `skills/ep-ai-manager@2.5.0` and `skills/project-self-docs@0.4.0`).
+- Check this self-docs set for staleness: compare `source_head` in each file's frontmatter against
+  `git rev-parse --short HEAD`, or read `docs/self-docs/self-docs-index.json` /
+  `docs/self-docs/CHANGES.jsonl` (written by
+  `.ai-assistance/skills/project-self-docs/scripts/self_docs_scan.py --write`).
+- No CI dashboard / pipeline exists to check (see `ARCHITECTURE.md` Diagrams section) -- unknown --
+  needs owner input if one exists outside this working tree.
+- Deeper runbook: none found beyond `CLAUDE.md` and `docs/worklog.md` -- unknown -- needs owner
+  input on whether a separate ops runbook exists elsewhere (e.g. a wiki/Confluence page).
+
+## Value & KPIs
+
+| Metric | Value (measured/estimated) | Source / dashboard |
+|---|---|---|
+| Gem version | `0.10.17` (`lib/ecoportal/api/version.rb`) | measured |
+| Downstream consumer repos | 3 (`ecoportal-api-v2`, `ecoportal-api-graphql`, `eco-helpers`) | measured (from `CLAUDE.md` dependency chain, cross-checked against `.ai-assistance/local/paths.json` fleet registry) |
+| Usage / adoption outside the known fleet chain | unknown -- needs owner input | rubygems.org download stats were not checked in this run |
+| Hours saved / delivery-speed impact | unknown -- needs owner input | No KPI telemetry specific to this gem was found in this repo (KPI tooling exists at the fleet level per `ep-ai-standards`, not evidenced as wired to this repo's own usage) |
+
+This section intentionally leaves the ROI/usage questions as `unknown -- needs owner input` rather
+than estimating a number with no evidentiary basis.

data/docs/self-docs/OVERVIEW.md

@@ -0,0 +1,61 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api"
+doc: overview
+last_generated: "2026-07-23"
+source_head: "69bf8e3"
+review_status: draft   # draft | reviewed  (only a human sets 'reviewed')
+---
+
+# Overview -- ecoportal-api
+
+## What this project is
+
+`ecoportal-api` is the foundational Ruby gem in the ecoPortal Ruby stack. It provides HTTP client
+infrastructure (retry, rate throttling, timeouts, APM), a shared response/model layer
+(`Ecoportal::API::Common`), and REST resources for the ecoPortal `internal` and `v1` APIs (people,
+schema fields, permissions, jobs). Every other gem in the chain (`ecoportal-api-v2`,
+`ecoportal-api-graphql`, `eco-helpers`) depends on this one, directly or transitively.
+(Evidence: `CLAUDE.md`, `lib/ecoportal/api/` tree, `ecoportal-api.gemspec`.)
+
+## Who it serves
+
+Internal: ecoPortal engineers who build the downstream gems (`ecoportal-api-v2`,
+`ecoportal-api-graphql`, `eco-helpers`) and any script/integration that talks to the ecoPortal API
+via those gems. It is a published RubyGem (`spec.homepage = "https://www.ecoportal.com"`,
+`rubygems_mfa_required: true` in the gemspec) -- unknown -- needs owner input on whether any
+external (non-ecoPortal-employee) consumer currently depends on it in production.
+
+## Current priority
+
+unknown -- needs owner input. `docs/worklog.md` (added 2026-07-22) records only the AI-standards
+alignment and session-handoff scaffold work; it does not state a current functional/feature
+priority for the gem itself. The most recent commits on `master` are all `chore(ai)`/`fix` AI-tooling
+work (alignment, settings hygiene), not feature development (evidence: `git log --oneline -20`).
+
+## At a glance
+
+- Repo type: Ruby gem (`ecoportal-api.gemspec` present; `rails-app`/`aws-cdk`/browser-extension
+  signals absent)
+- Primary language / runtime: Ruby, `required_ruby_version >= 3.2.2` (`ecoportal-api.gemspec`)
+- Entry points: `lib/ecoportal/api.rb` (gem root, `require 'dotenv/load'`), consumed by requiring
+  gem-namespaced files (`require 'ecoportal/api'`); `bin/console` and `bin/setup` for local
+  development (evidence: `bin/`, `README.md`)
+
+## Discovery & access
+
+The gem is distributed via the `Gemfile`/Bundler mechanism (`gem 'ecoportal-api'`, per `README.md`)
+and, per the gemspec, is releasable to rubygems.org via `bundle exec rake release`. Within
+ecoPortal, downstream teams discover it by being in the dependency chain documented in `CLAUDE.md`
+(`ecoportal-api -> ecoportal-api-v2 -> ecoportal-api-graphql -> eco-helpers`). unknown -- needs
+owner input on whether it is announced/listed anywhere beyond that chain (e.g. an internal
+catalogue), and on who outside the immediate dependency chain has access to the GitLab repo.
+
+## Related self-docs
+
+- Architecture: `ARCHITECTURE.md`
+- Conventions: `CONVENTIONS.md`
+- Integrations: `INTEGRATIONS.md`
+- Status: `STATUS.md`
+- Compliance: `COMPLIANCE.md`
+- Operations: `OPERATIONS.md`

data/docs/self-docs/STATUS.md

@@ -0,0 +1,71 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api"
+doc: status
+last_generated: "2026-07-23"
+source_head: "69bf8e3"
+review_status: draft
+# self_docs_mode (OD-008): OPTIONAL. Omit for the default (committed). Set to
+# gitignored-regenerate ONLY as an explicit declared opt-out (then document the regen path
+# below and gitignore docs/self-docs/). Optional key with a documented default -- does NOT
+# change schema_version.
+self_docs_mode: committed
+---
+
+# Status -- ecoportal-api
+
+**Note:** this is the most time-sensitive self-doc. Refresh it at cycle-end and after structural
+changes. Staleness is detectable via `source_head` vs the current git head.
+
+## Active work
+
+From the scanner's `activity_clusters` (last 50 commits) and `docs/worklog.md`:
+
+- AI tooling / standards alignment is the dominant recent activity: `.ai-assistance` (27 touches)
+  is nearly as hot as `lib` (28 touches) in the last 50 commits, and `CHANGELOG.md` (16 touches)
+  reflects the many small AI-alignment merges. Most recent work: deploying the
+  `project-self-docs` skill itself (`feat/deploy-project-self-docs`, MR !9, unmerged at the time
+  this doc was generated -- see below) and this self-docs generation run
+  (`feat/self-docs-generation`).
+- `lib` remains the primary code activity cluster, but this run did not analyse WHICH gem features
+  are in flight there -- unknown -- needs owner input on current feature-level priorities inside
+  `lib/`.
+
+## Migration state (if any)
+
+None found for the gem's own code. The AI-tooling side has an in-flight, not-yet-merged deploy:
+`feat/deploy-project-self-docs` (MR !9) adds the `project-self-docs` skill itself and is not yet on
+`master` as of this run (`git ls-tree origin/master` does not contain
+`.ai-assistance/skills/project-self-docs/`). This self-docs generation branch
+(`feat/self-docs-generation`) is based on that unmerged branch, so its MR should merge AFTER
+!9, not before.
+
+## Known risks
+
+- **AI-tooling churn vs code churn:** the AI-tooling directory (`.ai-assistance`) is nearly as
+  active as the actual gem source (`lib`) by commit-touch count over the last 50 commits. This is
+  not necessarily a problem, but it means a reader of `git log` alone could over-estimate recent
+  feature development. Flagging as observed, not judged.
+- **Changes to `Common::*` are a public API** for three downstream gems (`ecoportal-api-v2`,
+  `ecoportal-api-graphql`, `eco-helpers` per `CLAUDE.md`) -- any breaking change here has fleet-wide
+  blast radius and needs cross-repo coordination, which this self-docs run cannot verify is
+  currently happening in practice (process exists on paper in `CLAUDE.md`; adherence in practice is
+  unknown -- needs owner input).
+- No CI pipeline file exists in this repo (see `ARCHITECTURE.md` "Diagrams" section) -- unknown --
+  needs owner input on whether tests/lint run automatically anywhere before merge, or only locally
+  via `bundle exec rspec` / `bundle exec rubocop`.
+
+## Open questions
+
+- Is there an external (non-ecoPortal, non-fleet) consumer of the published `ecoportal-api` gem on
+  rubygems.org? (See `OVERVIEW.md`, `INTEGRATIONS.md`.) unknown -- needs owner input.
+- What is the actual current feature priority for the gem's own code (as opposed to AI-tooling
+  work)? `docs/worklog.md` does not currently record one. unknown -- needs owner input.
+- Does CI run via an inherited/external GitLab CI template not present as a file in this working
+  tree? unknown -- needs owner input.
+
+## Recent changes
+
+This is the first generation of this self-doc set (`docs/self-docs/` did not exist before this
+run -- scanner reported all seven files as `exists: false`). The machine-readable delta is
+recorded in `CHANGES.jsonl` in this same directory.

data/docs/self-docs/self-docs-index.json

@@ -0,0 +1,51 @@
+{
+  "schema_version": "1.1",
+  "generated_at": "2026-07-23T10:50:08Z",
+  "repo_name": "ecoportal-api",
+  "repo_type": "ruby-gem",
+  "head": "69bf8e3",
+  "docs": [
+    {
+      "file": "docs/self-docs/OVERVIEW.md",
+      "purpose": "What the project is, who it serves, current priority, discovery & access",
+      "exists": true,
+      "content_hash": "a819fa9d200c7ab7"
+    },
+    {
+      "file": "docs/self-docs/ARCHITECTURE.md",
+      "purpose": "Top-level structure, key components, how they fit",
+      "exists": true,
+      "content_hash": "49a7df216c5bdc07"
+    },
+    {
+      "file": "docs/self-docs/CONVENTIONS.md",
+      "purpose": "Coding style, branch naming, commit style, test conventions",
+      "exists": true,
+      "content_hash": "f45075d3f3ca043c"
+    },
+    {
+      "file": "docs/self-docs/INTEGRATIONS.md",
+      "purpose": "External services + data + permissions, upstream/downstream repos",
+      "exists": true,
+      "content_hash": "b5cb184b9e829040"
+    },
+    {
+      "file": "docs/self-docs/STATUS.md",
+      "purpose": "Active work, migration state, known risks, open questions",
+      "exists": true,
+      "content_hash": "147657c19c13c34e"
+    },
+    {
+      "file": "docs/self-docs/COMPLIANCE.md",
+      "purpose": "ISO-27001/audit, data classes + PII, vendors, AI content, leak controls",
+      "exists": true,
+      "content_hash": "802e24afbd20f486"
+    },
+    {
+      "file": "docs/self-docs/OPERATIONS.md",
+      "purpose": "Infrastructure, public exposure + Cloudflare, DevOps audit, usage KPIs",
+      "exists": true,
+      "content_hash": "475c09e0348a9187"
+    }
+  ]
+}

data/docs/worklog.md

@@ -0,0 +1,48 @@
+# Worklog -- ecoportal-api
+
+Session handoff log. Newest entry first -- read top-down at the start of every session.
+Format: `standards/workflows/session-handoff.md` in `ep-ai-standards`.
+
+---
+
+## 2026-07-23 -- Self-docs set generated (first time)
+
+generated by project-self-docs v0.4.0 per migration none, review_status: draft, run 2026-07-23
+
+### Done
+- Ran `project-self-docs` for the first time in this repo: generated the full
+  `docs/self-docs/` set (`OVERVIEW.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `INTEGRATIONS.md`,
+  `STATUS.md`, `COMPLIANCE.md`, `OPERATIONS.md`) plus `self-docs-index.json` and
+  `CHANGES.jsonl`. All docs carry `review_status: draft` -- pending human review before any
+  audit/hub use.
+- Several facts were marked `unknown -- needs owner input` where no evidence existed in this
+  repo (see each doc): current feature priority, external gem-consumer footprint, CI existence
+  outside this working tree, spec coverage thresholds, and a few PII/logging edge cases in
+  `COMPLIANCE.md`.
+
+### Blocked / Pending
+- Human review of the new self-docs set (`review_status: draft` on all seven files).
+- Base branch `feat/deploy-project-self-docs` (MR !9, adds the `project-self-docs` skill itself)
+  is still unmerged -- this generation's MR should merge AFTER !9.
+
+### Open Questions
+- See `docs/self-docs/STATUS.md` "Open questions" for the full list.
+
+---
+
+## 2026-07-22 -- AI standards alignment (session handoff scaffold)
+
+### Done
+- **AI standards alignment** -- repo brought to `ep-ai-standards` v1.9.1 (see
+  `.ai-assistance/standards-version.json`). Foundation scaffold (`CLAUDE.md`,
+  `.claude/settings.json`, `.ai-assistance/`, `ep-ai-manager` skill) confirmed in place.
+- **Session-handoff scaffold** -- created this `docs/worklog.md` and added the
+  "Read these first -- every session" pointer section to `CLAUDE.md`, closing the two
+  remaining `check-alignment.sh` residuals (`docs/worklog.md` missing, `CLAUDE.md` not
+  referencing it) that the earlier kit-only alignment pass deliberately left open.
+
+### Blocked / Pending
+- None.
+
+### Open Questions
+- None.

data/lib/ecoportal/api/common/client/with_retry.rb

@@ -5,8 +5,14 @@ module Ecoportal
         module WithRetry
           DELAY_REQUEST_RETRY       = 5
           RETRY_ATTEMPTS            = 5
+          # HTTP::TimeoutError is a SIBLING of HTTP::ConnectionError in the http gem's
+          # hierarchy (ConnectTimeoutError < TimeoutError < Error), so it must be listed
+          # explicitly: without it a transient connect/read/write timeout is never retried
+          # and kills a whole batch mid-loop (live-confirmed on the Farmers native card,
+          # 2026-07-30 — see multi_org_api FARMERS_NATIVE_MIGRATION.md).
           HANDLED_CONNECTION_ERRORS = [
             HTTP::ConnectionError,
+            HTTP::TimeoutError,
             IOError
           ].freeze
 

data/lib/ecoportal/api/common/client.rb

@@ -62,6 +62,8 @@ module Ecoportal
 
           return unless api_key.nil? || api_key.match(/\A\W*\z/)
           return unless self.version
+          return if self.version == 'graphql'
+          return if self.version == 'http'
 
           log(:error) { 'Api-key missing!' }
         end
@@ -69,11 +71,11 @@ module Ecoportal
         # Sends an http `GET` request against the api version using `path` to complete the base url,
         # and adding the key_value pairs of `params` in the http _header_.
         # @param path [String] the tail that completes the url of the request.
-        # @param params [Hash] the header paramters of the http request (not including the api key).
+        # @param params [Hash] the header parameters of the http request (not including the api key).
         # @option params [String] :page the current page we are requesting with given the `:per_page` offset.
         # @option params [String] :per_page the offset or the number of entries you get per request.
         # @option params [String] :q some text to search. Omit this parameter to target all the entries.
-        # @return [Common::Reponse] the basic custom response object.
+        # @return [Common::Response] the basic custom response object.
         def get(path, params: {})
           instrument('GET', path, params) do
             request do |http|
@@ -87,9 +89,9 @@ module Ecoportal
         # @note it automatically adds the http header param `Content-Type` as `application/json`
         # @param path [String] the tail that completes the url of the request.
         # @param data [String] the body of the query in json format.
-        # @param params [Hash] the header paramters of the http request (not including the api key).
+        # @param params [Hash] the header parameters of the http request (not including the api key).
         # @option params [String] URL params; will depend on he API being used.
-        # @return [Common::Reponse] the basic custom response object.
+        # @return [Common::Response] the basic custom response object.
         def post(path, data:, params: {})
           instrument('POST', path, params) do
             request do |http|
@@ -107,7 +109,7 @@ module Ecoportal
         # @note it automatically adds the http header param `Content-Type` as `application/json`
         # @param path [String] the tail that completes the url of the request.
         # @param data [String] the body of the query in json format.
-        # @return [Common::Reponse] the basic custom response object.
+        # @return [Common::Response] the basic custom response object.
         def patch(path, data:)
           instrument('PATCH', path, data) do
             request do |http|
@@ -118,7 +120,7 @@ module Ecoportal
 
         # Sends an http `DELETE` request against the api version using `path` to complete the base url.
         # @param path [String] the tail that completes the url of the request.
-        # @return [Common::Reponse] the basic custom response object.
+        # @return [Common::Response] the basic custom response object.
         def delete(path)
           instrument('DELETE', path) do
             request do |http|
@@ -132,14 +134,14 @@ module Ecoportal
         # @yield [http] launch specific http request.
         # @yieldparam http [HTTP] the http connection.
         # @yieldreturn [Common::Response] the basic custom response object.
-        # @return [Common::Reponse] the basic custom response object.
+        # @return [Common::Response] the basic custom response object.
         def request
           wrap_response yield(base_request)
         end
 
         # Wrap with basic custom object of the gem for responses.
         # @param response [HTTP::Response]
-        # @return [Common::Reponse] the basic custom response object.
+        # @return [Common::Response] the basic custom response object.
         def wrap_response(response)
           Ecoportal::API::Common::Response.new(response)
         end
@@ -151,7 +153,7 @@ module Ecoportal
         def base_request
           @base_request ||=
             case @version
-            when 'v2'
+            when 'v2', 'v3'
               HTTP.headers('X-ECOPORTAL-API-KEY' => api_key).accept(:json)
             else
               HTTP.headers('X-ApiKey' => api_key).accept(:json)
@@ -205,7 +207,7 @@ module Ecoportal
         #   log(:info) {'General information on what's going on'}
         #   log(:warn) {'This is a warning that something is likely to have gone amiss'}
         #   log(:error) {'Something went wrong'}
-        #   log(:fatal) {'An unrecoverable error has happend'}
+        #   log(:fatal) {'An unrecoverable error has happened'}
         # @param level [Symbol] the level that the message should be logged.
         # @yield [] generates the message.
         # @yieldreturn [String] the generated message.

data/lib/ecoportal/api/version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    VERSION = '0.10.15'.freeze
+    VERSION = '0.10.17'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api
 version: !ruby/object:Gem::Version
-  version: 0.10.15
+  version: 0.10.17
 platform: ruby
 authors:
 - Tapio Saarinen
@@ -200,6 +200,35 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ai-assistance/.gitignore"
+- ".ai-assistance/bridge/.gitignore"
+- ".ai-assistance/bridge/CLAUDE.md"
+- ".ai-assistance/bridge/archive/.gitkeep"
+- ".ai-assistance/bridge/inbox/.gitkeep"
+- ".ai-assistance/bridge/outbox/.gitkeep"
+- ".ai-assistance/capabilities/assumptions-log.md"
+- ".ai-assistance/scripts/bridge-inbox-check.sh"
+- ".ai-assistance/scripts/bridge-init.sh"
+- ".ai-assistance/scripts/confine-to-subtree.sh"
+- ".ai-assistance/scripts/dirty-tree-guard.sh"
+- ".ai-assistance/scripts/distill_procedural.py"
+- ".ai-assistance/scripts/log-mcp-access.sh"
+- ".ai-assistance/scripts/log-skill-usage.sh"
+- ".ai-assistance/scripts/log_mcp_access.py"
+- ".ai-assistance/scripts/observe-session.sh"
+- ".ai-assistance/scripts/observe_session.py"
+- ".ai-assistance/scripts/protect-host-paths.sh"
+- ".ai-assistance/scripts/scrub.py"
+- ".ai-assistance/scripts/scrub.py.sha256"
+- ".ai-assistance/scripts/surface-procedural.sh"
+- ".ai-assistance/scripts/surface_procedural.py"
+- ".ai-assistance/skills/ep-ai-manager/SKILL.md"
+- ".ai-assistance/skills/project-self-docs/SKILL.md"
+- ".ai-assistance/skills/project-self-docs/scripts/self_docs_scan.py"
+- ".ai-assistance/standards-version.json"
+- ".ai-assistance/version.json"
+- ".claude/.gitignore"
+- ".claude/settings.json"
 - ".gitignore"
 - ".markdownlint.json"
 - ".rspec"
@@ -207,12 +236,23 @@ files:
 - ".ruby-version"
 - ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
+- docs/self-docs/ARCHITECTURE.md
+- docs/self-docs/CHANGES.jsonl
+- docs/self-docs/COMPLIANCE.md
+- docs/self-docs/CONVENTIONS.md
+- docs/self-docs/INTEGRATIONS.md
+- docs/self-docs/OPERATIONS.md
+- docs/self-docs/OVERVIEW.md
+- docs/self-docs/STATUS.md
+- docs/self-docs/self-docs-index.json
+- docs/worklog.md
 - ecoportal-api.gemspec
 - lib/ecoportal/api.rb
 - lib/ecoportal/api/common.rb