ecoportal-api-graphql 1.3.12 → 1.3.13

data/docs/self-docs/OVERVIEW.md

@@ -1,9 +1,9 @@
 ---
-schema_version: "1.0"
+schema_version: "1.1"
 repo: "ecoportal-api-graphql"
 doc: overview
-last_generated: "2026-07-06"
-source_head: "2abd6fc"
+last_generated: "2026-07-09"
+source_head: "3f7b877"
 review_status: draft   # draft | reviewed  (only a human sets 'reviewed')
 ---
 
@@ -43,9 +43,22 @@ threading).
 - Entry points: `require 'ecoportal/api-graphql'` -> `lib/ecoportal/api-graphql.rb` ->
   `Ecoportal::API::GraphQL` (`lib/ecoportal/api/graphql.rb`)
 
+## Discovery & access
+
+Access model: **on-request, developer-scoped** -- this is a Ruby gem, not a self-serve product. It
+reaches its users (the ecoPortal Integrations Team and internal script authors) by being declared as
+a dependency in a consuming project's Gemfile/gemspec (e.g. `eco-helpers ~> 1.3, >= 1.3.4`), not by
+a public listing or an end-user-facing install. Developers learn it exists through the team's
+integration-gem stack documentation (`.ai-assistance/code/ecoPortal_architecture/11_integration_gems.md`),
+the repo README, and this self-docs set once mirrored to the EP Projects Register. There is no
+customer-facing discovery surface: end customers never interact with the gem directly; they see only
+the ecoPortal platform it talks to.
+
 ## 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

@@ -1,9 +1,9 @@
 ---
-schema_version: "1.0"
+schema_version: "1.1"
 repo: "ecoportal-api-graphql"
 doc: status
-last_generated: "2026-07-06"
-source_head: "2abd6fc"
+last_generated: "2026-07-09"
+source_head: "3f7b877"
 review_status: draft
 ---
 
@@ -65,5 +65,9 @@ intent. The #1-priority project is Template Automatic Build and Maintenance (see
 
 ## Recent changes
 
-First generation of the self-docs set (draft, for the EP Projects Register pilot). Generated at
-git head `2abd6fc` on branch `main`. The machine-readable delta is in `CHANGES.jsonl`.
+Upgraded the self-docs set to schema 1.1 (audit/compliance surface): added `COMPLIANCE.md` and
+`OPERATIONS.md`, enriched `INTEGRATIONS.md` (data class + PII + permissions per tie) and `OVERVIEW.md`
+(Discovery & access), and bumped all docs to `source_head` `3f7b877`. Everything remains
+`review_status: draft` -- a human must set `reviewed` before any audit use. Prior state: first
+generation at git head `2abd6fc` (EP Projects Register pilot). The machine-readable delta is in
+`CHANGES.jsonl`.

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

@@ -1,15 +1,15 @@
 {
-  "schema_version": "1.0",
-  "generated_at": "2026-07-06T11:15:00Z",
+  "schema_version": "1.1",
+  "generated_at": "2026-07-09T07:08:00Z",
   "repo_name": "ecoportal-api-graphql",
   "repo_type": "ruby-gem",
-  "head": "2abd6fc",
+  "head": "3f7b877",
   "docs": [
     {
       "file": "docs/self-docs/OVERVIEW.md",
-      "purpose": "What the project is, who it serves, current priority",
+      "purpose": "What the project is, who it serves, current priority, discovery & access",
       "exists": true,
-      "content_hash": "391055c9a6a687b9"
+      "content_hash": "c403012498ab9247"
     },
     {
       "file": "docs/self-docs/ARCHITECTURE.md",
@@ -25,15 +25,27 @@
     },
     {
       "file": "docs/self-docs/INTEGRATIONS.md",
-      "purpose": "External services, upstream/downstream repos, dependencies",
+      "purpose": "External services + data + permissions, upstream/downstream repos",
       "exists": true,
-      "content_hash": "bae9f91748e33af1"
+      "content_hash": "d271ac76361e4638"
     },
     {
       "file": "docs/self-docs/STATUS.md",
       "purpose": "Active work, migration state, known risks, open questions",
       "exists": true,
-      "content_hash": "08841d1d45eea2d6"
+      "content_hash": "1acf51a3e7822dfb"
+    },
+    {
+      "file": "docs/self-docs/COMPLIANCE.md",
+      "purpose": "ISO-27001/audit, data classes + PII, vendors, AI content, leak controls",
+      "exists": true,
+      "content_hash": "1e72c2356b4e3579"
+    },
+    {
+      "file": "docs/self-docs/OPERATIONS.md",
+      "purpose": "Infrastructure, public exposure + Cloudflare, DevOps audit, usage KPIs",
+      "exists": true,
+      "content_hash": "878b50d02339acb7"
     }
   ]
 }

data/docs/worklog.md

@@ -8,6 +8,24 @@ This file tracks cross-project session state and the overall repo status.
 
 ---
 
+## ▶ SESSION 2026-07-10 — OD-001 decision-support delivered to ep-ai-standards (breadcrumb)
+
+Produced a decision-support doc mapping this repo's REAL GraphQL mutation surface onto
+ep-ai-standards' operation-class ladder for OD-001 (the GraphQL gateway PROD "low-risk"
+auto-approval threshold / provisional Dial A). Evidence-based from live introspection
+(`.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json` -- 190 mutations)
++ code-specs + `lib/ecoportal/api/graphql/mutation/**`. Key findings: register-type axis is
+real + in-schema (`Register.registerStatus: TESTING|LIVE`, `base/register.rb:7`); org-type
+(sandpit/uat/demo/PROD) is NOT a schema field (infra/credential-level, `base/organization.rb`
+exposes only id/name/companyName/logoUrl); several mutations do not map cleanly (payload-hidden
+deletions in `updatePage`, bulk/cascade, cross-env UAT->PROD deploy, egress/email/credential
+mints). Delivered to ep-ai-standards' bridge inbox as
+`ecoportal-api-graphql-od001-mutation-mapping.md` (STATUS: PENDING) -- a PROPOSAL for the graphql
+team + Oscar to validate via an ep-ai-standards MR. NO code changed in this repo. Does not change
+OD-001's ruling. (OD-007 breadcrumb convention.)
+
+---
+
 ## ▶ SESSION 2026-07-05 — 3 live act-gov crashes = ONE root cause (stale released gems); fixed-stack floors
 
 Three live crashes on act-gov (`-toocs-coding` + org-structure sync), all the **same class**: the

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

@@ -29,6 +29,8 @@ module Ecoportal
 
             puts "Configuring GraphQL Client onto '#{url}'"
 
+            pp email
+
             super(
               url,
               headers:      {

data/lib/ecoportal/api/common/graphql/http_client.rb

@@ -1,177 +1,189 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        class ResponseError < StandardError; end
-
-        class HttpClient < Common::Client
-          class << self
-            def base_url(host)
-              "#{protocol(host)}://#{host}"
-            end
-
-            def protocol(host)
-              host.match(/^localhost|^127\.0\.0\.1/)? 'http' : 'https'
-            end
-          end
-
-          ENDPOINT_PATH = 'external/graphql'.freeze
-          READ_TIMEOUT  = 90
-          WRITE_TIMEOUT = 90
-
-          attr_reader :host, :version
-
-          include Ecoportal::API::Common::GraphQL::AuthService
-
-          def initialize(
-            email:        nil,
-            pass:         nil,
-            org_id:       nil,
-            api_key:      nil,
-            version:      'graphql',
-            host:         'live.ecoportal.com',
-            logger:       ::Logger.new(IO::NULL),
-            deep_logging: false,
-            no_schema:    true
-          )
-            @org_id      = org_id
-            @user_email  = email
-            @user_pass   = pass
-            @no_schema   = no_schema
-            @version     = version
-
-            super(
-              api_key:      api_key,
-              host:         host,
-              logger:       logger,
-              deep_logging: deep_logging
-            )
-          end
-
-          # Creates a HTTP object adding the `X-ApiKey` or `X-ECOPORTAL-API-KEY` param to the header, depending on the API version.
-          # @note It configures HTTP so it only allows body data in json format.
-          # @return [HTTP] HTTP object.
-          def base_request
-            @base_request ||=
-              case @version
-              when NilClass, 'http'
-                HTTP
-              when 'v1', 'v0'
-                HTTP.headers('X-ApiKey' => key_token)
-              when 'v2', 'v3'
-                HTTP.headers('X-ECOPORTAL-API-KEY' => key_token)
-              when 'graphql'
-                HTTP.headers('Authorization' => "Bearer #{session_token(host: host)}")
-              end.then do |request|
-                request ||= HTTP
-                request.accept(:json).timeout(
-                  read:  READ_TIMEOUT,
-                  write: WRITE_TIMEOUT
-                )
-              end
-          end
-
-          def org_id
-            @org_id || fetch_env_required('ORGANIZATION_ID')
-          end
-
-          # Executes a GraphQL query or mutation over HTTP.
-          # @param query_string [String] full GraphQL query document.
-          # @param variables [Hash] variable values to pass to the operation.
-          # @param operation_name [String, nil] when the document has multiple operations.
-          # @return [Hash] parsed response body (string-keyed, includes 'data' and optionally 'errors').
-          # @raise [Ecoportal::API::Common::Client::Error::UnexpectedServerError] on non-2xx HTTP status.
-          # @raise [Ecoportal::API::Common::GraphQL::ResponseError] when the response body contains GraphQL errors.
-          def execute(query_string, variables: {}, operation_name: nil)
-            body = { query: query_string, variables: variables }
-            body[:operationName] = operation_name if operation_name
-            response = base_request.post(url_for(''), json: body)
-            handle_http_response(response)
-          end
-
-          # Full URl builder of the request
-          # @param path [String] the tail that completes the url of the request.
-          # @return [String] the final url.
-          def url_for(path)
-            "#{api_url}#{path}"
-          end
-
-          private
-
-          def key_token
-            return                           if http?
-            return session_token(host: host) if graphql?
-            return @api_key                  if api_key?
-            return ENV['ORG_INT_KEY']        if v0?
-
-            puts 'Api-key missing!'
-          end
-
-          def api_url
-            base_url.then do |url|
-              next "#{url}/api/#{version}"                 if v1_0? || v2_3?
-              next "#{url}/api/#{org_id}/#{ENDPOINT_PATH}" if graphql?
-
-              url
-            end
-          end
-
-          def base_url
-            @base_url ||= self.class.base_url(host)
-          end
-
-          def protocol
-            @protocol ||= self.class.protocol(host)
-          end
-
-          def http?
-            return true if @version.nil?
-
-            @version == 'http'
-          end
-
-          def api_key?
-            @api_key && !@api_key.match(/\A\W*\z/)
-          end
-
-          def v1_0?
-            v1? || v0?
-          end
-
-          def v1?
-            @version == 'v1'
-          end
-
-          def v0?
-            @version == 'v0'
-          end
-
-          def v2_3?
-            return true if @version == 'v2'
-            return true if @version == 'v3'
-
-            false
-          end
-
-          def graphql?
-            @version == 'graphql'
-          end
-
-          def handle_http_response(response)
-            unless response.status.success?
-              raise Ecoportal::API::Common::Client::Error::UnexpectedServerError.new(
-                response.body.to_s, code: response.status.code
-              )
-            end
-
-            parsed = response.parse(:json)
-            errors = parsed['errors']
-            raise ResponseError, errors.map { |e| e['message'] }.join('; ') if errors&.any?
-
-            parsed
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        class ResponseError < StandardError; end
+
+        class HttpClient < Common::Client
+          class << self
+            def base_url(host)
+              "#{protocol(host)}://#{host}"
+            end
+
+            def protocol(host)
+              host.match(/^localhost|^127\.0\.0\.1/)? 'http' : 'https'
+            end
+          end
+
+          ENDPOINT_PATH = 'external/graphql'.freeze
+          READ_TIMEOUT  = 90
+          WRITE_TIMEOUT = 90
+
+          attr_reader :host, :version
+
+          include Ecoportal::API::Common::GraphQL::AuthService
+
+          def initialize(
+            email:        nil,
+            pass:         nil,
+            org_id:       nil,
+            api_key:      nil,
+            version:      'graphql',
+            host:         'live.ecoportal.com',
+            logger:       ::Logger.new(IO::NULL),
+            deep_logging: false,
+            no_schema:    true
+          )
+            @org_id      = org_id
+            @user_email  = email
+            @user_pass   = pass
+            @no_schema   = no_schema
+            @version     = version
+
+            super(
+              api_key:      api_key,
+              host:         host,
+              logger:       logger,
+              deep_logging: deep_logging
+            )
+          end
+
+          # Creates a HTTP object adding the `X-ApiKey` or `X-ECOPORTAL-API-KEY` param to the header, depending on the API version.
+          # @note It configures HTTP so it only allows body data in json format.
+          # @return [HTTP] HTTP object.
+          def base_request
+            @base_request ||=
+              case @version
+              when NilClass, 'http'
+                HTTP
+              when 'v1', 'v0'
+                HTTP.headers('X-ApiKey' => key_token)
+              when 'v2', 'v3'
+                HTTP.headers('X-ECOPORTAL-API-KEY' => key_token)
+              when 'graphql'
+                HTTP.headers('Authorization' => "Bearer #{session_token(host: host)}")
+              end.then do |request|
+                request ||= HTTP
+                request.accept(:json).timeout(
+                  read:  READ_TIMEOUT,
+                  write: WRITE_TIMEOUT
+                )
+              end
+          end
+
+          def org_id
+            @org_id || fetch_env_required('ORGANIZATION_ID')
+          end
+
+          # Executes a GraphQL query or mutation over HTTP.
+          # @param query_string [String] full GraphQL query document.
+          # @param variables [Hash] variable values to pass to the operation.
+          # @param operation_name [String, nil] when the document has multiple operations.
+          # @return [Hash] parsed response body (string-keyed, includes 'data' and optionally 'errors').
+          # @raise [Ecoportal::API::Common::Client::Error::UnexpectedServerError] on non-2xx HTTP status.
+          # @raise [Ecoportal::API::Common::GraphQL::ResponseError] when the response body contains GraphQL errors.
+          def execute(query_string, variables: {}, operation_name: nil)
+            body = { query: query_string, variables: variables }
+            body[:operationName] = operation_name if operation_name
+
+            # Route through the inherited `Common::Client` pipeline
+            # (`instrument` -> `with_retry` { `rate_throttling` }) so GraphQL requests
+            # inherit the SAME battle-tested contingencies as the REST clients:
+            # rate-limit backoff (429 / Cloudflare 1015), 5xx + connection-error retries,
+            # timeouts, and instrumentation. Do NOT re-issue the request raw here — that
+            # bypasses all of the above and is what let live runs die on the first 429.
+            response = instrument('POST', ENDPOINT_PATH, body) do
+              request { |http| http.post(url_for(''), json: body) }
+            end
+
+            handle_http_response(response)
+          end
+
+          # Full URl builder of the request
+          # @param path [String] the tail that completes the url of the request.
+          # @return [String] the final url.
+          def url_for(path)
+            "#{api_url}#{path}"
+          end
+
+          private
+
+          def key_token
+            return                           if http?
+            return session_token(host: host) if graphql?
+            return @api_key                  if api_key?
+            return ENV['ORG_INT_KEY']        if v0?
+
+            puts 'Api-key missing!'
+          end
+
+          def api_url
+            base_url.then do |url|
+              next "#{url}/api/#{version}"                 if v1_0? || v2_3?
+              next "#{url}/api/#{org_id}/#{ENDPOINT_PATH}" if graphql?
+
+              url
+            end
+          end
+
+          def base_url
+            @base_url ||= self.class.base_url(host)
+          end
+
+          def protocol
+            @protocol ||= self.class.protocol(host)
+          end
+
+          def http?
+            return true if @version.nil?
+
+            @version == 'http'
+          end
+
+          def api_key?
+            @api_key && !@api_key.match(/\A\W*\z/)
+          end
+
+          def v1_0?
+            v1? || v0?
+          end
+
+          def v1?
+            @version == 'v1'
+          end
+
+          def v0?
+            @version == 'v0'
+          end
+
+          def v2_3?
+            return true if @version == 'v2'
+            return true if @version == 'v3'
+
+            false
+          end
+
+          def graphql?
+            @version == 'graphql'
+          end
+
+          # @param response [Ecoportal::API::Common::Response] the wrapped response
+          #   produced by the inherited pipeline (body already JSON-parsed).
+          def handle_http_response(response)
+            unless response.success?
+              raise Ecoportal::API::Common::Client::Error::UnexpectedServerError.new(
+                response.src_body, code: response.status.code
+              )
+            end
+
+            parsed = response.body
+            errors = parsed && parsed['errors']
+            raise ResponseError, errors.map { |e| e['message'] }.join('; ') if errors&.any?
+
+            parsed
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GRAPQL_VERSION = '1.3.12'.freeze
+    GRAPQL_VERSION = '1.3.13'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-graphql
 version: !ruby/object:Gem::Version
-  version: 1.3.12
+  version: 1.3.13
 platform: ruby
 authors:
 - Oscar Segura
@@ -262,6 +262,7 @@ files:
 - ".ai-assistance/projects/api-v2-to-graphql-migration/UPSTREAM.md"
 - ".ai-assistance/projects/api-v2-to-graphql-migration/notes/csv-template-pipeline-design.md"
 - ".ai-assistance/projects/api-v2-to-graphql-migration/notes/cutover-usecase-gap-audit.md"
+- ".ai-assistance/projects/compat-layer-audit/COMPAT_AUDIT.md"
 - ".ai-assistance/projects/dynamic-model-generation/INTENT.md"
 - ".ai-assistance/projects/eco-helpers-compat/INTENT.md"
 - ".ai-assistance/projects/eco-helpers-compat/MIGRATION_GUIDE.md"
@@ -291,9 +292,13 @@ files:
 - ".ai-assistance/projects/template-maintenance/DESIGN.md"
 - ".ai-assistance/projects/template-maintenance/PHASE0-FINDINGS.md"
 - ".ai-assistance/projects/template-maintenance/README.md"
+- ".ai-assistance/projects/template-model-logic/CATEGORY_CATALOG.md"
+- ".ai-assistance/projects/template-model-logic/CLASSIFICATION_SPIKE.md"
+- ".ai-assistance/projects/template-model-logic/DESIGN_NOTE.md"
 - ".ai-assistance/projects/workflow-space/TODO.md"
 - ".ai-assistance/reinstall-claude-desktop-windows.md"
 - ".ai-assistance/scripts/CLAUDE.md"
+- ".ai-assistance/scripts/bridge-inbox-check.sh"
 - ".ai-assistance/scripts/bridge-init.sh"
 - ".ai-assistance/scripts/bridge-status.sh"
 - ".ai-assistance/scripts/capabilities-check.ts"
@@ -323,6 +328,8 @@ files:
 - ".ai-assistance/skills/graphql-schema-analysis/SKILL.md"
 - ".ai-assistance/skills/procedural-memory/SKILL.md"
 - ".ai-assistance/skills/project-cycle/SKILL.md"
+- ".ai-assistance/skills/project-self-docs/SKILL.md"
+- ".ai-assistance/skills/project-self-docs/scripts/self_docs_scan.py"
 - ".ai-assistance/skills/refactor/SKILL.md"
 - ".ai-assistance/skills/rubocop/SKILL.md"
 - ".ai-assistance/skills/ruby-scripting/SKILL.md"
@@ -334,6 +341,7 @@ files:
 - ".env.example"
 - ".gitattributes"
 - ".gitignore"
+- ".gitlab-ci.yml"
 - ".markdownlint.json"
 - ".rspec"
 - ".rubocop.yml"
@@ -350,8 +358,10 @@ files:
 - bin/setup.ps1
 - 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