ecoportal-api-graphql 1.3.5 → 1.3.9

data/.ai-assistance/code/ecoPortal_architecture/03_api_layers.md

@@ -0,0 +1,147 @@
+# EcoPortal API Layers
+
+---
+
+## Overview
+
+EcoPortal has three API access layers, each serving different purposes and eras:
+
+| Layer | Type | Status | gem |
+|-------|------|--------|-----|
+| APIv1 (OAuth) | REST | Active — auth only | n/a (direct HTTP) |
+| APIv2 | REST | **BEING RETIRED** (~2026-06-07 + 3 weeks) | `ecoportal-api-v2` |
+| GraphQL API | GraphQL | **Current standard** | `ecoportal-api-graphql` |
+| APIv3 (page render) | REST (likely) | In development — custom exports | Not yet public |
+
+---
+
+## Authentication (APIv1 / OAuth)
+
+All access goes through OAuth 2.0 password grant:
+
+```
+POST https://live.ecoportal.com/oauth/token
+Content-Type: application/json
+
+{
+  "grant_type": "password",
+  "email": "user@example.com",
+  "password": "..."
+}
+```
+
+Response includes `access_token` (Bearer) and `refresh_token`.
+
+**Token refresh:**
+```
+POST /oauth/token
+{ "grant_type": "refresh_token", "refresh_token": "..." }
+```
+
+The `access_token` is passed as `Authorization: Bearer <token>` on all subsequent calls.
+
+---
+
+## APIv2 (REST) — Being Retired
+
+**Base URL:** `https://live.ecoportal.com/api/<org_id>/`
+
+**Ruby gem:** `Ecoportal::API::V2` in `ecoportal-api-v2`
+
+**Local path:** `C:\ruby_scripts\git\ecoportal-api-v2`
+
+**Key characteristics:**
+- REST API with resource-based endpoints
+- Returns full page documents as JSON
+- Stage rendering: one GET request per stage (pages with stages must be fetched
+  stage-by-stage due to access control — each stage can have different user permissions)
+- Only pages WITHOUT stages AND templates can be fetched/updated as a whole document
+- Full document sent on update (partial updates not cleanly supported)
+- Page updates tracked via `as_update` (dirty diff) which generates a JSON patch
+
+**eco-helpers interface:**
+```ruby
+apiv2.pages.get(id, stage_id: nil)        # fetch page (or specific stage)
+apiv2.pages.get_new(template_id)           # build draft from template
+apiv2.pages.create(page, from: template_id) # create instance
+apiv2.pages.update(page)                   # save changes
+apiv2.registers.search(register_id, opts) { |result| ... }  # paginated search
+```
+
+---
+
+## GraphQL API — Current Standard
+
+**Endpoint:** `POST https://live.ecoportal.com/api/<org_id>/external/graphql`
+
+**Headers required:**
+- `Content-Type: application/json`
+- `Authorization: Bearer <access_token>`
+
+**Request payload:**
+```json
+{
+  "query": "query MyQuery($id: ID!) { ... }",
+  "variables": { "id": "..." },
+  "operationName": "MyQuery"
+}
+```
+
+**Key characteristics:**
+- ONE endpoint — no URL variation by resource
+- Client specifies exactly which fields to return
+- Full page fetched in ONE request (all stages included)
+- Stage-specific operations via `stageId` parameter
+- `patchVer` required on all update mutations (optimistic concurrency)
+- Multiple mutations can be combined in one request (executed in declaration order)
+- `searchConf` is a Hash type (`Search`) — not a typed GraphQL input
+
+**GraphQL gem:** `Ecoportal::API::GraphQL` in `ecoportal-api-graphql`
+
+**Local path:** `C:\ruby_scripts\git\ecoportal-api-graphql` (THIS REPO)
+
+**Schema reference:** Live schema at `https://live.ecoportal.com/api-docs/graphql`
+(requires login). Updated on every deployment.
+
+---
+
+## APIv3 (Page Render / Custom Exports) — In Development
+
+**Purpose:** Custom page rendering for exports (PDF, etc.). Provides a page render
+endpoint separate from the main GraphQL API.
+
+**Status:** In development as of 2026-06-07. Not yet production-stable for scripting.
+Not covered in this gem.
+
+---
+
+## APIv2 vs GraphQL: Key Differences for Scripts
+
+| Concern | APIv2 | GraphQL |
+|---------|-------|---------|
+| Stage fetch | One request per stage | Full page in one request |
+| Field IDs | Available after get | Available after buildFromTemplate |
+| Update scope | Full doc or stage doc | Partial: only specify what changes |
+| patchVer | Not required (v2 handles internally) | **REQUIRED** on all updates |
+| Filter format | `{ type: "date_filter", lbound:, ubound: }` | `{ operation: "date_filter", params: { gte:, lte: } }` |
+| Archived pages | Search returns them with flag | Default excluded; `includeArchived: true` opt-in |
+| Template update | Supported | **NOT recommended** (Engineering block) |
+| Search result | Full page data | Org: full DB page; Register: ES preview only |
+
+---
+
+## eco-helpers Compat Layer
+
+Since APIv2 is being retired, the `ecoportal-api-graphql` gem provides a compatibility
+layer so existing eco-helpers scripts can work without modification:
+
+```ruby
+graphql = Ecoportal::API::GraphQL.new(email:, pass:, org_id:)
+graphql.pages     # → Compat::Pages (same interface as apiv2.pages)
+graphql.registers # → Compat::Registers (same interface as apiv2.registers)
+```
+
+Page models include `Concerns::SnakeCamelAccess` — all camelCase methods accessible
+as snake_case (`external_id`, `patch_ver`, `source_template_id`, `creator_name`, etc.).
+
+See `11_integration_gems.md` for full compat layer details.

data/.ai-assistance/code/ecoPortal_architecture/04_graphql_queries_mutations.md

@@ -0,0 +1,277 @@
+# EcoPortal GraphQL Queries and Mutations
+
+---
+
+## Query Root (`currentOrganization`)
+
+All queries nest under `currentOrganization`. There is no top-level resource query —
+everything is scoped to the authenticated user's organisation.
+
+```graphql
+{
+  currentOrganization {
+    id
+    # All other queries go here
+  }
+}
+```
+
+---
+
+## Page Queries
+
+### `page(id: ID!)` → `PageUnion`
+
+Fetches a single page by ID. Returns `BasicPage | PhasedPage`.
+
+```graphql
+query GetPage($id: ID!) {
+  currentOrganization {
+    page(id: $id) {
+      ...PageFields         # core metadata
+      ...PhasedPageFields   # stage index (if phased)
+    }
+  }
+}
+```
+
+**Gem class:** `Query::Page`
+**For compat (full data):** Use `...CommonPageUnion` fragment (includes all field data).
+
+### `pages(...)` → `PageUnionConnection`
+
+Org-wide paginated page search. Returns full `PageUnion` from DB.
+
+**Arguments:**
+- `searchConf: Search` — filter/sort/query configuration
+- `templatesOnly: Boolean` — restrict to templates only
+- `showHiddenData: Boolean` — include hidden fields
+- `after/before/first/last` — cursor pagination
+
+**Performance note:** ~3 seconds per page on render (DB-backed). Avoid large result sets.
+
+```graphql
+query OrgSearchPages($searchConf: Search, $first: Int, $after: String) {
+  currentOrganization {
+    pages(searchConf: $searchConf, first: $first, after: $after) {
+      totalCount
+      pageInfo { hasNextPage endCursor }
+      nodes { ...PageFields }
+    }
+  }
+}
+```
+
+**Gem class:** `Query::Pages`
+
+### `templates(...)` → `PageConnection`
+
+Lists templates (pages with `templatesOnly: true`). Same arguments as `pages`.
+
+**Gem class:** `Query::Templates`
+
+### `register(id:) { previewPages(...) }` → `PreviewPageConnection`
+
+ES-backed fast register search. Returns `PreviewPage` — metadata only, no field IDs.
+
+**Arguments on `previewPages`:**
+- `searchConf: Search`
+- `includeArchived: Boolean` (default false)
+- `presetViewId: ID` — apply a register PageView preset
+
+**Performance:** Sub-second (Elasticsearch). Use for metadata lookup.
+**Limitation:** No `patchVer`, no field IDs. Cannot be used for mutation input building.
+
+```graphql
+query RegisterSearch($registerId: ID!, $search: Search, $includeArchived: Boolean) {
+  currentOrganization {
+    register(id: $registerId) {
+      previewPages(searchConf: $search, includeArchived: $includeArchived) {
+        totalCount
+        pageInfo { hasNextPage endCursor }
+        nodes { id uid name state archived externalId createdAt { dateTime } }
+      }
+    }
+  }
+}
+```
+
+**Gem class:** `Query::RegisterPreviewPages`
+
+### `pageDelta(deltaInput: [DeltaInput!]!, searchConf: Search)` → `[DeltaResult!]!`
+
+Cache-invalidation query. Given a list of `{ id, deltaAt }` pairs, returns which pages
+have changed since the given timestamp.
+
+**`DeltaResult`:** `{ id: ID!, delta: DeltaEnum! }` where `DeltaEnum = UPDATED | NOT_FOUND | NEW`
+
+**Gem class:** `Query::PageDelta`
+
+---
+
+## Page Mutations
+
+### `buildPageFromTemplate(input: BuildFromTemplateInput!)` → `BuildFromTemplatePayload`
+
+**Step (a) of the 2-step create sequence.** Builds a draft without persisting it.
+Returns a `PageUnion` with server-assigned field IDs (the template's field IDs mapped
+to new instance IDs). Use these IDs to populate `dataFields.updates` in `createFromTemplate`.
+
+```graphql
+mutation BuildPage($input: BuildFromTemplateInput!) {
+  buildPageFromTemplate(input: $input) {
+    errors { details fullMessages }
+    item { ...CommonPageUnion }
+  }
+}
+```
+
+**Variables:** `{ templateId: "...", showHiddenData: true }`
+
+### `createPageFromTemplate(input: CreateFromTemplateInput!)` → `CreateFromTemplatePayload`
+
+**Step (b) of the 2-step create sequence.** Creates the page from a filled draft.
+
+**Key `CreateFromTemplateInput` fields:**
+- `templateId: ID!`
+- `dataFields: DataFieldOneToManyInput!` — field values to set on creation
+- `page: PageInput` — page-level fields (name, state, locations, etc.)
+- `showHiddenData: Boolean`
+- `stageId: ID` — target stage
+- `submit: Boolean` — submit immediately
+- `draft: Boolean` — create as draft
+
+### `updatePage(input: UpdatePageInput!)` → `UpdatePagePayload`
+
+Updates an existing page.
+
+**Key `UpdatePageInput` fields:**
+- `id: ID!`
+- `patchVer: Int` — **MUST match current page patchVer**
+- `page: PageInput` — page-level fields to change
+- `dataFields: DataFieldOneToManyInput` — field updates and/or additions
+- `stageId: ID` — target specific stage (required for stage submit/close-out)
+- `submit: Boolean` — submit the stage (triggers task assignment server-side)
+- `publish: Boolean` — publish a draft page
+- `showHiddenData: Boolean`
+
+**DataFieldOneToManyInput:**
+```json
+{
+  "updates":   [{ "plainText": { "id": "FIELD_ID", "value": "..." } }],
+  "additions": [{ "date": { "id": "NEW_ID", "value": "..." } }],
+  "deletions": ["FIELD_ID_TO_DELETE"]
+}
+```
+
+### `archivePage(input: ArchivePageInput!)` / `unarchivePage(...)` → payload with `item: PageUnion`
+
+Archive/unarchive a page.
+
+**Production pattern (compound mutation):**
+When a page has a unique `externalId`, archive the externalId first to prevent conflicts
+on future re-creation, then archive:
+
+```graphql
+mutation ArchivePage($id: ID!, $blank_external_id: Boolean = true) {
+  updatePage(input: { id: $id, page: { externalId: null } })
+    @include(if: $blank_external_id) {
+    item { id externalId }
+  }
+  archivePage(input: { id: $id }) {
+    item { id archived }
+    errors { details fullMessages }
+  }
+}
+```
+
+This compound mutation (two in one request) was designed for stateless middleware
+clients that cannot sequence separate HTTP calls.
+
+---
+
+## Fragments
+
+### `PageFields` (on `BasePageInterface`)
+
+Core metadata fragment — always include `__typename` for `PageUnion` dispatch.
+
+Fields: `__typename id name uid icon patchVer state archived archivedAt draft externalId
+timeZone otherTags taskPriority sourceTemplateId createdAt updatedAt creatorName locations { ...LocationNode }`
+
+**Gem:** `Fragment::PageFields` in `fragment/page.rb`
+
+### `BasicPageFields` (on `BasicPage`)
+
+Sections available directly on BasicPage:
+```graphql
+fragment BasicPageFields on BasicPage {
+  sections { __typename ... on ContentSection { id heading } ... on SplitSection { id heading } }
+}
+```
+
+**Gem:** `Fragment::BasicPageFields`
+
+### `PhasedPageFields` (on `PhasedPage`)
+
+Stage index for phased pages (lightweight — no data fields):
+```graphql
+fragment PhasedPageFields on PhasedPage {
+  stagesIndex { id name ordering state started hasCompleteTask hasReviewTask }
+  currentStage { id name ordering state }
+  activeStages  { id name ordering }
+}
+```
+
+**Gem:** `Fragment::PhasedPageFields`
+
+### `CommonPageUnion` (on `PageUnion`) — THE STANDARD FRAGMENT
+
+The comprehensive fragment covering all customer integration patterns.
+Located in `Fragment::Pages` (sub-namespace, accessed via `fragment.pages.assemble(:CommonPageUnion)`).
+
+**Boolean variables controlling payload:**
+
+| Variable | Purpose |
+|---|---|
+| `$content` | Include field values, stage completion info, files, people |
+| `$only_content` | Exclude structural/config — content values only |
+| `$fields` | Include field definitions (labels, types, options — needed for mutation input building) |
+
+**Three use cases:**
+1. **Build from template** — `$fields: true, $content: false` → get field structure + IDs
+2. **Fetch before update** — `$content: true, $fields: true` → current values + IDs for mutation
+3. **Verify after create/update** — `$content: true, $only_content: true` → confirm result
+
+**Fragment source:** `lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb`
+**Documented in:** Jira API Docs space (Confluence APIDOCS)
+
+### `LocationNode` (on `LocationNodeInterface`)
+
+Location node fragment with ancestors and classifications. Automatically assembled
+when `...LocationNode` appears in a query via the recursive `assemble_fragments` mechanism.
+
+---
+
+## Fragment Assembly (How It Works)
+
+The gem scans query strings for `...FragmentName` spreads and assembles the needed
+fragment definitions RECURSIVELY. A fragment that references another fragment
+(e.g. `PageFields → ...LocationNode`) is resolved automatically.
+
+Sub-namespaces (`Fragment::Pages`) are registered via `Fragment.register_namespace(Pages)`
+so `Fragment.assemble(:CommonPageUnion)` finds it.
+
+---
+
+## Other Key Queries
+
+### `contractorEntities(...)` → `ContractorEntityConnection`
+### `actionCategories(...)` → `ActionCategoryConnection`
+### `action(id:)` → `Action`
+### `actions(...)` → `ActionConnection`
+### `locationStructure(id:)` → `LocationStructure`
+### `locationStructures(...)` → `LocationStructureConnection`
+### `registers(...)` → register list
+### `personMembers(...)` → `PersonMemberConnection`
+### `pageDelta(...)` → cache invalidation

data/.ai-assistance/code/ecoPortal_architecture/05_page_workflows.md

@@ -0,0 +1,200 @@
+# EcoPortal Page Workflows
+
+---
+
+## The 2-Step Create Sequence
+
+Creating a page from a template ALWAYS requires two steps because MongoDB assigns field
+IDs at creation time — the client must know these IDs to populate field values.
+
+### Step A: Build from Template
+
+```ruby
+# GraphQL
+payload = Mutation::Page::BuildFromTemplate.new(client).query(
+  input: { templateId: template_id, showHiddenData: true }
+) do
+  item { spread :CommonPageUnion }
+end
+draft = payload.item
+```
+
+This returns a `PageUnion` with:
+- All field definitions for the template (labels, types, options)
+- Server-assigned field IDs (instance IDs, NOT template field IDs)
+- Default values where configured
+- Stage structure (for PhasedPage)
+
+**Important:** The returned page is NOT persisted yet.
+
+### Step B: Fill and Create
+
+```ruby
+# Modify fields using the instance field IDs from the draft
+draft.components.get_by_name('Job Number').value = 'JOB-001'
+draft.components.get_by_type(:select).find { |f| f.label == 'Status' }.select_option('Active')
+
+# Build field updates from dirty fields
+field_updates = draft.data_fields_updates  # → [DataFieldInput, ...]
+
+# Create the page
+payload = Mutation::Page::CreateFromTemplate.new(client).query(
+  input: {
+    templateId: template_id,
+    dataFields: { updates: field_updates },  # uses instance field IDs from draft
+    page: { externalId: 'EXT-001', name: 'My Record' }
+  }
+)
+ref = Compat::PageReference.new(payload.item)
+# ref.page_id → the created page's ID
+# ref.active_stage_id → ID of the first active stage
+```
+
+---
+
+## The 2-Step Update Sequence
+
+Updating a page ALWAYS requires fetching first to get:
+1. `patchVer` — required for optimistic concurrency
+2. Current field IDs — for building `dataFields.updates`
+3. Current field values — for computing changes
+
+### Step A: Fetch Current Page
+
+```ruby
+page = Query::Page.new(client).query(id: page_id) do
+  spread :CommonPageUnion
+end
+# OR via compat layer:
+page = graphql.pages.get(page_id)
+```
+
+### Step B: Modify and Update
+
+```ruby
+# Modify page-level fields
+page.name = 'Updated Name'
+page.external_id = 'NEW-EXT-001'
+
+# Modify data fields
+page.components.get_by_name('Summary').value = 'Updated summary'
+
+# Send update
+input = Input::Page::Update.from_model(page)
+# input[:patchVer] — injected automatically from page.patchVer
+# input[:page]     — page-level changes
+# input[:dataFields] — field-level changes
+payload = Builder::Page.new(client).update(input: input)
+```
+
+**Why patchVer matters:** If two scripts update the same page concurrently, the second
+update will fail with a stale-patchVer error. Re-fetch the page to get the new patchVer.
+
+---
+
+## Stage Submit / Close-Out Sequence
+
+When a stage needs to be submitted (triggering task assignment on the next stage):
+
+```ruby
+# Fetch page with full stage data
+page = graphql.pages.get(page_id)
+
+# Get stage view for the specific stage
+stage_view = graphql.pages.get(page_id, stage_id: 's1_id')
+# stage_view.sections, stage_view.components → filtered to this stage only
+
+# Fill in field data for this stage
+stage_view.components.get_by_name('Risk Level').select_option('High')
+
+# Submit the stage
+input = Input::Page::Update.from_model(
+  stage_view,
+  stage_id: 's1_id',
+  submit:   true
+)
+payload = Builder::Page.new(client).update(input: input)
+```
+
+**What `submit: true` triggers server-side:**
+- Stage state changes to `complete`
+- Next fill-in task (`CompletePage`) is created and assigned per workflow rules
+- Or if review is configured: `ReviewPage` task is created
+- People fields scoped to the next stage may generate access grants
+
+**Important:** Without `stageId`, the server may not correctly associate the submit
+with the right stage. Always include `stageId` when submitting a specific stage.
+
+---
+
+## Archive Sequence
+
+Standard archive (no externalId concern):
+```ruby
+payload = Builder::Page.new(client).archive(input: { id: page_id })
+```
+
+With externalId blanking (production pattern for deduplication safety):
+```graphql
+mutation ArchivePage($id: ID!, $blank_external_id: Boolean = true) {
+  updatePage(input: { id: $id, page: { externalId: null } })
+    @include(if: $blank_external_id) {
+    item { id }
+  }
+  archivePage(input: { id: $id }) {
+    item { id archived }
+    errors { details fullMessages }
+  }
+}
+```
+
+---
+
+## Find-Before-Create (Deduplication Pattern)
+
+To prevent creating duplicate pages based on a unique identifier:
+
+```ruby
+# Step 1: Search for existing page
+conf = SearchConf.new
+  .filter(SearchConf::Register.new(register_id))
+  .filter(SearchConf::Exact.new(:external_id, 'EXT-001'))
+
+result = org.pages(searchConf: conf.to_h, first: 1)
+existing = result.nodes.first
+
+if existing
+  # Page exists — update it
+  page = graphql.pages.get(existing.id)
+  # ... modify and update
+else
+  # Page doesn't exist — create it
+  draft = graphql.pages.get_new(template_id)
+  # ... fill and create
+end
+```
+
+**Why org search (not register search):** Register search (`previewPages`) is ES-backed
+and fast, but returns `PreviewPage` without field IDs or `patchVer`. For update workflows,
+always use org search (`pages`) with `register_filter` to get the full page.
+
+---
+
+## Simulate / Dry Run Mode (eco-helpers Pattern)
+
+eco-helpers scripts support a dry-run mode where changes are computed but not sent:
+
+```ruby
+# In eco-helpers, dirty? checks for pending changes
+if dirty?(page)
+  if simulate?
+    puts "Would update: #{pages.get_body(page).inspect}"
+  else
+    pages.update(page)
+    page.consolidate!  # reset dirty tracking
+  end
+end
+```
+
+The `get_body(page)` method returns `page.as_update` — the computed change diff.
+`consolidate!` resets the `original_doc` baseline so the page is no longer dirty.