ecoportal-api 0.10.16 → 0.10.17

data/docs/self-docs/INTEGRATIONS.md

@@ -0,0 +1,62 @@
+---
+schema_version: "1.1"
+repo: "ecoportal-api"
+doc: integrations
+last_generated: "2026-07-23"
+source_head: "69bf8e3"
+review_status: draft
+---
+
+# Integrations -- ecoportal-api
+
+**Purpose:** the ties this project has to other systems and repos. This is the section the central
+hub uses to trace inter-project dependencies and surface reuse (ADR-015 Section 5). It records, per tie,
+the DATA that flows and the PERMISSIONS required -- feeding the compliance (vendor/PII) and the
+cross-project-permissions questions. Detailed data-handling lives in `COMPLIANCE.md`.
+
+## External services
+
+| Service | Purpose | Data sent (class + PII?) | Auth / permissions (scopes) |
+|---|---|---|---|
+| ecoPortal REST API (`live.ecoportal.com` default host, `Common::Client::DEFAULT_HOST`) | The actual product API this gem is a client for (internal + v1 resources: people, schema, permissions, jobs) | Whatever the consuming application sends -- can include customer/employee data (people records) depending on caller; class = customer/employee data, PII likely YES (person records) -- see `COMPLIANCE.md` | `api_key` param, sent as `X-ApiKey` header (evidence: `client.rb` docstring "the `api_key` will be automatically added as parameter `X-ApiKey`") |
+| Elastic APM / Elastic Cloud (`https://<account_id>.apm.<region>.aws.cloud.es.io:<port>`, default region `ap-southeast-2`) | Optional error/transaction telemetry (`ElasticApmIntegration`, only reports `UnexpectedServerError`s, `transaction_sample_rate: 0.1`) | APM traces/error metadata -- unknown -- needs owner input on whether response bodies (which could carry customer data) are ever included in a reported error vs just status/class | `ELASTIC_APM_KEY`, `ELASTIC_APM_ACCOUNT_ID`, `ELASTIC_APM_REGION`, `ELASTIC_APM_PORT` env vars (`elastic_apm_integration.rb`); fails open (disables itself) on any `StandardError` at start, never crashes the host app |
+| RubyGems.org | Package distribution for the published gem (`bundle exec rake release` per `README.md`) | Gem source code only, no runtime data | Publisher credentials (rubygems.org account); `rubygems_mfa_required: true` in the gemspec |
+
+## Upstream dependencies (repos we depend on)
+
+None -- `ecoportal-api` is the foundational/first gem in the ecoPortal Ruby chain (`CLAUDE.md`:
+"the foundational REST API gem"). It has no ecoPortal-owned upstream gem dependency; its runtime
+dependencies (`dotenv`, `elastic-apm`, `http`, `rate_throttle_client`) are third-party gems from
+the gemspec, not ecoPortal repos.
+
+| Repo / package | What we use it for | Permission/scope required (if any) |
+|---|---|---|
+| `dotenv` (~> 3) | Loads `.env` into `ENV` on gem require (`lib/ecoportal/api.rb: require 'dotenv/load'`) | none |
+| `elastic-apm` (>= 4.7, < 5) | Optional APM client, see External services above | `ELASTIC_APM_KEY` etc. |
+| `http` (~> 5.1, < 6) | The actual HTTP client library `Common::Client` wraps | none |
+| `rate_throttle_client` (~> 0.1) | Client-side rate throttling used by `Common::Client::RateThrottling` | none |
+
+## Downstream consumers (who depends on us)
+
+Per `CLAUDE.md`'s documented chain: `ecoportal-api-v2` -> `ecoportal-api-graphql` -> `eco-helpers`
+(each real repo, confirmed present in `.ai-assistance/local/paths.json` in the `ep-ai-standards`
+fleet registry: aliases `ep-api-v2`, `ep-graphql`, `eco-helpers`). `ecoportal-api-v2` in particular
+"extends [`Common::BaseModel`/`Common::BaseClass`] heavily" (`CLAUDE.md`). unknown -- needs owner
+input on any consumer outside that four-repo chain (e.g. ad hoc scripts elsewhere in the
+organisation that `gem install ecoportal-api` directly).
+
+## Key package dependencies
+
+From `ecoportal-api.gemspec` (runtime, not the full `Gemfile.lock`):
+
+- `dotenv` (~> 3)
+- `elastic-apm` (>= 4.7, < 5)
+- `http` (~> 5.1, < 6)
+- `rate_throttle_client` (~> 0.1)
+
+Development-only: `pry`, `rake`, `redcarpet`, `rspec`, `rubocop`, `rubocop-rake`, `yard`.
+
+## Feature-request-not-rebuild note
+
+None identified this run -- no evidence in `docs/worklog.md` or recent commits of a feature that
+duplicates another project's scope. unknown -- needs owner input if a specific case comes up later.

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/version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    VERSION = '0.10.16'.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.16
+  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"
@@ -214,6 +243,16 @@ files:
 - 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