ecoportal-api-graphql 1.3.4 → 1.3.9

data/CHANGELOG.md

@@ -1,470 +1,673 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-
-## [1.3.5] - 2025-09-xx
-
-### Added
-
-### Changed
-
-### Fixed
-
-## [1.3.4] - 2025-09-04
-
-### Added
-
-- Command execution result: **added** command doc when there's a `results` error.
-- Payload improvements:
-  - On `LocationsError.validationErrors`: fetch `property` property.
-  - On **results**, `Command` always fetch `__typename` and the other properties.
-
-### Changed
-
-- Changed base `error_doc`: **consistent property name**
-
-### Fixed
-
-- Correct fetch on `ok` (sometimes it is `null`: that doesn't mean failed).
-- **Consistent order** on `error?` and `error_doc`.
-- `Draft`
-  - **Overlapping** name `ConflictingIds` (vs `LocationsError.conflictingIds`)
-  - **Wrong** include on `FetchNested`
-
-## [1.3.3] - 2025-08-29
-
-### Added
-
-- Better error handling
-
-### Fixed
-
-- Unused parameter/variable `$includeArchivedNodes`
-
-## [1.3.2] - 2025-08-19
-
-### Added
-
-- `Mutation`: allow parameters other than **input**.
-- Location Structure `Draft` models
-- `Interface::LocationStructure::Nodes` for `LocationStructure` and `Draft::Structure`
-- `raw_response` as optional query parameter (for debugging)
-- `Logic::Input` (out of consistency)
-- Fragments:
-  - `LocationDraft`
-  - `LocationsError`
-- Query to include `draft` list when fetching an **RS**.
-- Location `Draft` queries:
-  - `Draft#byId`
-  - `Draft#create`
-  - `Draft#delete`
-  - `Draft#addCommands`
-  - `Draft#publish`
-  - `Draft#dropBadCommands`
-- Error tracking througout the payload models of location mutations
-
-### Changed
-
-- Upgrade dependency (`ecoportal-api` **gem**).
-- Moved rescue on fragment definition to `#define` itself.
-- `NodeInterface` moved to `Interface::LocationStructure::Node`
-- Code: Shorten namespace referral.
-- Swap to `Logic::BaseModel`
-- `Mutation` to introduce `:input` required parameter by using parent class.
-
-### Fixed
-
-- `QueryConnection`: bad code.
-- `conflictingIds` should be array.
-
-## [1.3.1] - 2025-06-11
-
-### Changed
-
-- upgraded gem dependencies
-- **Moded** `Ecoportal::API::GraphQL::Base::Model` to
-  - > `Ecoportal::API::GraphQL::BaseModel`
-- **Added** `Interface::LocationNode`
-- **Added** `Interface::BasePage`
-
-### Fixed
-
-- **Fragments**
-  - `Action` fragment to use `PageUnion` (**upgrade**)
-  - **Memoize** fragments.
-  - Add what fragment failed in the **error**.
-
-## [1.2.1] - 2025-05-16
-
-### Changed
-
-- upgrade `ecoportal-api` gem
-- upgrade `ecoportal-api-v2` gem
-
-## [1.1.1] - 2025-05-14
-
-### Added
-
-- `MemberChanges` helpers for `Base::ContractorEntity`
-- Custom **Diff** logic that can be used in GraphQL content:
-  - `Common::GraphQL::Model::Diffable::HashDiffNesting`
-    - Reused from `HashDiffPatch` (`ecoportal-api-v2`):
-      1. It does not use `patch_ver`, but rather just `id` property alone.
-      2. The _operation_ property has been renamed to `api_operation` (to ensure no collisions). And the operation types are symbols, and renamed to: `:delete`, `:update` and `:create`. This can show up to be useful when, for instance, reusing the output of `#as_update` to generate actual input objects (i.e. `#as_input`) that feed some GraphQL query.
-      3. The _data_ property has been renamed to `change_data`.
-      4. `Hash` **keys** are of type `Symbol`.
-  - `Common::GraphQL::Model::Diffable::DiffService`. In a GraphQL context, this aims to be able to implement a function called `#as_input` (equivalent to `#as_update`):
-      1. It uses the `HashDiffNesting` helpers.
-      2. It has capability to `ignore` certain keys.
-      3. It can calculate **diff** excluding nested models (i.e. those that are `root?` and, therefore, not part of the changed target model). This functionality is an optimization to `cascaded_callbacks` throughout the nested models.
-
-### Changed
-
-- `Common::GraphQL::Model::Diffable` by using `Diffable::DiffService` (with `cascaded_callbacks` implementation).
-  - `#as_update`
-  - `#dirty?`
-- upgraded `ecoportal-api` gem
-- updraded `ecoportal-api-v2` gem
-
-## [0.4.7] - 2025-04-02
-
-### Added
-
-- `page.id` to Action linked resources.
-
-## [0.4.6] - 2025-04-02
-
-### Added
-
-- `Ecoportal::API::GraphQL::Logic::QueryConnection`
-  - **Require** `default_connection_block` to child classes
-  - This aims to **not** having have client code having to define the block for `#each`
-
-### Changed
-
-- upgraded `ecoportal-api` gem
-- upgraded `ecoportal-api-v2` gem
-
-## [0.4.5] - 2025-03-14
-
-### Added
-
-- Query `actionCategories`
-- Mutation **create** `Action`
-
-### Changed
-
-- `Action` model to have `locations` (**RS** upgrade)
-
-## [0.4.4] - 2025-02-23
-
-### Changed
-
-- Upgraded `ecoportal-api` gem (maintanance)
-- Upgraded `ecoportal-api-v2` gem (to provision `root!` class method)
-- Defined some models that hand on their own as `root!`
-- Refactored `Base::Model` by moving its loggic to `Common::GraphQL`
-
-### Fixed
-
-- `Ecoportal::API::Common::GraphQL::HashHelpers`
-  - Truly make the iterator generic
-
-## [0.4.3] - 2024-11-21
-
-### Changed
-
-- upgrade gems
-  - `ecoportal-api`
-  - `ecoportal-api-v2`
-- `Ecoportal::API::Common::GraphQL::HttpClient.new` ceased to default `version` to `v1` (now it defaults to `nil`)
-
-## [0.4.2] - 2024-10-01
-
-### Changed
-
-- upgrade gems
-  - `ecoportal-api-v2`
-- add explicit dependency onto `ecoportal-api` gem (client)
-
-## [0.4.1] - 2024-08-09
-
-### Added
-
-- `ContractorEntity` added field `externalId`
-
-### Changed
-
-- gem upgrade `ecoportal-api-v2`
-
-## [0.4.0] - 2024-08-01
-
-### Changed
-
-- require `ruby 3`
-
-## [0.3.18] - 2024-05-16
-
-### Fixed
-
-- `Ecoportal::API::GraphQL::Payload::LocationStructure::CommandExecutionResult`
-  - Error is nullable
-
-## [0.3.17] - 2024-05-14
-
-### Fixed
-
-- `field_name` should add up to the path
-
-## [0.3.16] - 2024-04-29
-
-### Added
-
-- Exposed `graphql` `ContractorEntity` `destroy`
-
-### Fixed
-
-- incorrect loading
-
-### Changed
-
-- Input for ContractorEntity create moved as `update` (as it wasn't correct)
-
-## [0.3.15] - 2024-04-13
-
-### Added
-
-- `Ecoportal::API::GraphQL::Logic::BaseQuery`
-  - `::base_path` class instance var.
-- query to retrieve `currentOrganization.classifications`
-
-### Fixed
-
-- upgraded `ecoportal-api-v2` gem
-
-## [0.3.14] - 2024-03-13
-
-### Added
-
-- some benchmarking on
-  1. core graphql base `query`
-- `#parent_id` to location node model
-
-### Changed
-
-- upgraded `ecoportal-v2-api` gem
-
-### Fixed
-
-- Optimized `treeify` and locations structure class
-
-## [0.3.13] - 2024-02-03
-
-### Changed
-
-- upgrade `ecoportal-api-v2`
-
-## [0.3.12] - 2024-01-27
-
-### Added
-
-- Exposed `graphql` `Action` `update` and get a single `action`
-
-## [0.3.11] - 2023-09-19
-
-### Added
-
-- Exposed `graphql` `ContractorEntity` `create` and `update`
-
-## [0.3.10] - 2023-08-12
-
-### Fixed
-
-- `Ecopotal::API::GraphQL::Query::LocationStructure`
-  - `query` in basic_block missed an explicitly declared parameter.
-
-## [0.3.9] - 2023-08-03
-
-### Added
-
-- `Ecoportal::API::GraphQL::Logic::BaseQuery`
-  - Added support for **default** values.
-
-## [0.3.8] - 2023-07-18
-
-### Added
-
-- Integration for archiving actions.
-- `LocationNodeInterface` -> support for `classifications`
-- `Treeify` to dump more data per node (classifications)
-
-### Fixed
-
-- Silenced waning messages when redefining `Fragment`s
-
-## [0.3.7] - 2023-05-23
-
-### Fixed
-
-- `Ecoportal::API::Common::GraphQL::Client` adjusted `read_timeout` and `write_timeout` to `90` seconds.
-
-## [0.3.6] - 2023-04-17
-
-### Changed
-
-- Softened max version of **gem** dependencies
-
-### Fixed
-
-- `Ecoportal::API::GraphQL::Fragment#define` was not removing previous constants
-  - Changed check method to be `::const_defined?`
-
-## [0.3.5] - 2023-04-03
-
-### Fixed
-
-- `Ecoportal::API::GraphQL::Helpers::LocationsTree#treeify`
-  - Make it real id-case-insensitive (parents in lower case were being missed due to this)
-
-## [0.3.4] - 2023-04-03
-
-### Added
-
-- `Ecoportal::API::Common::GraphQL::AuthService`
-  - `#session_token` added **token auto-renew** functionality (when token expires in less than 90 minutes)
-  - `#session_token_renewed`
-
-### Fixed
-
-- Enabled to specify `host` (other than `live.ecoportal.com`) by the user
-
-## [0.3.3] - 2023-04-02
-
-### Fixed
-
-- `Ecoportal::API::GraphQL::Base::LocationNode` **added** attribute `archivedToken`
-
-## [0.3.2] - 2023-04-02
-
-### Changed
-
-- `Ecoportal::API::GraphQL::Helpers::LocationsTree#treeify` added support for `archived_token`
-
-## [0.3.1] - 2023-03-09
-
-### Changed
-
-- Upgraded core gem dependency `ecoportal-api-v2`
-
-## [0.2.3] - 2023-02-27
-
-### Fixed
-
-- Typo in tests LocationsStructures... should read `locationStructures`
-
-## [0.2.2] - 2023-02-24
-
-### Fixed
-
-- Build gem correctly
-
-## [0.2.1] - 2023-02-24
-
-### Changed
-
-- Migrate from TagTrees to **reporting structures** (breaking change)
-
-### Added
-
-- Basics for reporting structure mutations
-
-## [0.1.11] - 2022-11-29
-
-### Added
-
-- `Ecoportal::API::GraphQL::Base::Mutation`
-- Added `createContractorEntity`
-
-### Changed
-
-- **upgraded** `graphlient` gem dependency (support for framents)
-  - removed patch in this gem
-- Slight internal refactor of `Ecoportal::API::GraphQL::Base::Query`
-- Upgraded `ecoportal-api-v2` **gem** dependency
-
-## [0.1.10] - 2022-09-29
-
-### Changed
-
-- **upgraded** `ecoportal-api-v2` gem dependency
-
-### Fixed
-
-- Remove debugging message
-
-## [0.1.9] - 2022-09-26
-
-### Added
-
-- `Ecoportal::API::GraphQL::Query::TagTree`
-
-### Changed
-
-- **upgraded** `ecoportal-api-v2` gem dependency
-- added `Ecoportal::API::Common::GraphQL::QueryIntegration`
-  - restructured `Ecoportal::API::GraphQL::Model::Organization` class
-- **Patch** on `Graphlient::Query` for fragments support (**pull request**: <https://github.com/ashkan18/graphlient/pull/94>)
-
-## [0.1.8] - 2022-09-23
-
-### Added
-
-- `currentOrganization.tagTrees` query
-
-### Changed
-
-- **upgraded** `ecoportal-api-v2` gem dependency
-- Restructured the `Query` inheritance chain to make things simpler
-
-## [0.1.6] - 2022-09-19
-
-### Fixed
-
-- Call to **private** method `remove_const` in `Ecoportal::API::GraphQL::Fragment#define`
-
-## [0.1.5] - 2022-09-19
-
-### Added
-
-- Patch `GraphQL::Query#append_node` so we can use Fragments in blocks using `___` as start of the constant, and `__` for namespace separator
-  - Issue/feature request: <https://github.com/ashkan18/graphlient/issues/93>
-- `Ecoportal::API::GraphQL::Fragment#define` provided that client scripts can create their own fragments in their own namespace
-  - Exposed `Ecoportal::API::GraphQL#fragments`
-  - It will always (re)define in the `Fragment` root namespace
-
-## [0.1.4] - 2022-09-16
-
-### Fixed
-
-- Able to inject connection block to `each`
-- Error handling delegated to parent class (`QueryConnection`)
-- Retrieve `id` on elements of `Array`
-
-## [0.1.3] - 2022-09-15
-
-### Fixed
-
-- Fixed circular reference to `org_id` in `Ecoportal::API::Common::GraphQL::Client`
-
-## [0.1.2] - 2022-09-15
-
-### Changed
-
-- `Ecoportal::API::GraphQL` addded `email` and `pass` parameters on initialization
-  - This allows for integration in some client lib
-
-## [0.1.0] - 2022-09-15
-
-### Added
-
-- First commit with some basic structure
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+## [1.3.9] - 2026-07-02
+
+APIv2→GraphQL cutover hardening (backwards-compatible). Live-validated on the maintained ooze
+integrations (toocs-coding, cans-upsert).
+
+### Fixed
+
+- **Faithful dry-run body** — `Compat::Pages#get_body` returns the SAME input `#update`/`#create`
+  would send (under the `'page'` key), incl. `dataFields.updates` (invisible to `page.as_update`
+  on phased pages). Create previews render as `CreateFromTemplateInput` (marker-based
+  `#new_draft?`) instead of mislabelling as updates.
+- **Stage submit/sign-off carries `stageId`** — `Input::Page::Update.from_model` raises if a
+  submit/task is requested without a stage; `Compat::StageView` records the viewed stage on the
+  page; `compat_stage_id` resolves pinned → active(stage-view) → current. People-field
+  permissions are stage-scoped, so a submit must name its stage.
+- **`CrossReference#dirty?`** compares the reference-id SET vs `original_doc` — no phantom
+  `referenceIds: []` clears (empty→empty / same→same is not dirty).
+- **`Number`/`Gauge` blank → nil, never `0.0`** — an empty CSV cell no longer coerces to a real
+  zero. Shared `DataField#numeric_or_nil`.
+- **`People` reader** falls back to the `people{id}` nodes when `peopleIds` is blank — an append
+  can't wipe existing people.
+- **`Compat::Pages#create` resolves `templateId` from the get_new marker**
+  (`_compat_source_template_id`), matching the dry-run — fixes a live `templateId: null` failure.
+
+### Added
+
+- **Exact-match register filter** — `Compat::FilterTranslator` maps a v2 `type: 'exact_filter'`
+  (alias `'is_filter'`) → GraphQL `is_filter` (whole-value equality on a field's `.exact` keyword
+  subfield), deriving the `membranes.<type>` path. Fixes exact-id existence checks (partial
+  `match_filter` missed exact SKUs → duplicate pages). Note: case-insensitive, first-64-chars.
+- **`Builder::Page#archive(clear_external_id:)`** — optionally blanks `externalId` (a separate
+  `updatePage`) before archiving, for cleanup of a failed/duplicate creation; default `false`
+  keeps it. externalId is the per-org, per-model integration pairing key.
+
+## [1.3.8] - 2026-06-12
+
+### Added
+
+- **Template mutations** — full lifecycle for creating and updating workflow templates:
+  - `Mutation::Template::{Create,Update}` — `createPageTemplate` / `updatePageTemplate` (both accept `WorkflowCommandInput` command bus)
+  - `Mutation::Template::{Publish,Unpublish}` — `publishTemplate` / `unpublishTemplate`
+  - `Mutation::Template::UpdateInformation` — update template `description`, `aiDescription`, `templateType`
+  - `Mutation::Template::{CreateRelatedPage,DestroyRelatedPage}` — manage template related-pages
+  - `Builder::Template` wired as `api.template`
+- **`updateVariableBindings`** — `Mutation::Page::UpdateVariableBindings` maps named force variable slots to data field IDs on a page; `Input::VariableBinding` value object
+- **Kickstand job mutations** — `Mutation::Kickstand::{StartJob,FailJob,BulkUpdateJobs}`; `Builder::Kickstand` extended with `start_job`, `fail_job`, `bulk_update_jobs`
+
+## [1.3.7] - 2026-06-12
+
+### Added
+
+- **PagesWorkflow space (W1–W5)**
+  - `Base::PagesWorkflow` + sub-model tree (`pages_workflow/`): `RegisterField`, `CallbackType`,
+    `OperationInterface`, `TriggerInterface`, and supporting types — read model for the
+    page-workflow configuration (`autoPageCreationEnabled`, `fields`, `stages`).
+  - `Model::PagesWorkflow` with class resolver.
+  - **Workflow command bus**: `Input::WorkflowCommandInput` covering ~80 command types under
+    `input/workflow_command/`. `Mutation::Page::ExecuteWorkflowCommands` +
+    `Payload::ExecuteWorkflowCommands`.
+  - Workflow fragments registered for assembly.
+  - _Note: the workflow command surface is volatile upstream — designed to absorb change._
+- **Force model / ForceCompat**
+  - `Base::Force` (+ `force/` sub-models), Force fragment.
+  - `Mutation::Page::ExecuteForceCommands`, `Payload::ForceCommands`, `Query::PageWithForces`.
+- **DataField type hierarchy (Phase E)**
+  - Full set of typed `Base::Page::DataField` subclasses: `PlainText`, `RichText`, `DateField`,
+    `Number`, `Gauge`, `People`, `Select`, `Checklist`, `TagField`, `Geo`, `Signature`,
+    `ContractorEntities`, `CrossReference`, `ImageGallery`, `FileField`, `Mailbox`,
+    `ActionsList`, `Law`, `AiSummary`, `Table`, `SmartFill`, dispatched via `TYPE_MAP`/`from_doc`.
+  - `DataField::Collection` — `dirty_inputs`, `dirty_additions`, `dirty_deletions`,
+    `add`, `mark_for_deletion`.
+- **Register builder & models**
+  - `Builder::Register` (+ `register/preset_view`), `Model::Register`,
+    `Mutation::Register` (`create`/`update`/`destroy`), `Input::Register`, `Payload::Register`.
+- **Preset views**
+  - `Model::PresetView`, `Mutation::PresetView` (`create`/`update`/`destroy`/`permission`),
+    `Query::RegisterPresetViews`, `Input::PresetView`, `Payload::PresetView`.
+- **AI mutations**
+  - `Mutation::SmartFill` (`generate`/`submit_feedback`).
+  - `Mutation::AiSummary` (`generate`/`submit_feedback`), `Model::AiSummaryVersion`,
+    `Payload::AiSummaryGenerate`.
+- **Review task & draft lifecycle mutations**
+  - Review tasks: `approve`/`reject`/`restart`/`undo`/`batch_update` (`Mutation::Page::*ReviewTask`),
+    `Payload::Page::ReviewTask`.
+  - Drafts: `Mutation::Page::CreateDraft`/`PublishDraft`/`DeleteDraft`, `Payload::Page::Draft`.
+  - Templates: `Mutation::Page::BuildFromTemplate`/`CreateFromTemplate` + payloads.
+- **Queries**
+  - `Query::PageDelta` (+ `Base::DeltaResult`, `Input::DeltaInput`).
+  - `Query::RegisterPreviewPages` (+ `Base::PreviewPage`).
+  - `Query::FileUploadSignature` + file-upload helper.
+- **`Input::SearchConf`** — fluent/chainable filter DSL and `SearchConf.from_description`
+  (AI-assisted filter generation from natural language).
+- **Compat layer for `eco-helpers`** — `Compat::Pages` (`#each` cursor-paginated full iteration),
+  `Compat::Registers`, `Compat::FilterTranslator`, `Compat::PageReference`,
+  `Compat::StageCollection`, `Compat::StageView`, `Compat::SearchResults`, `Compat::Response`.
+- **Concerns** — `SnakeCamelAccess` (camelCase→snake_case delegation), `DataFieldAccess`,
+  `PageCompat`, `Deprecation`.
+- `Payload::OkPayload` base payload.
+- **Page read layer (Phase A)**
+  - `Fragment::PageFields` — named fragment on `BasePageInterface` covering identity, state,
+    lifecycle, and location fields. Includes `__typename` for union dispatch.
+  - `Interface::BasePage` — added `passboolean :draft` and `passthrough :externalId`.
+  - `Base::Page::Basic < Interface::BasePage` — concrete basic page class.
+  - `Base::Page::Phased` — `passarray :stages` (raw array until typed in Phase C).
+  - `Model::Page::Basic`, `Model::Page::Phased` — concrete model classes with class resolvers.
+  - `Model::PageUnion` — factory module: dispatches `.new(doc)` to `Basic` or `Phased`
+    based on `__typename`. Used as `item_class` / `node_class` throughout.
+  - `Connection::Page < Logic::Connection` — paginated page connection with `PageUnion` nodes.
+  - `Query::Page` (single page by ID), `Query::Pages` (paginated list), `Query::Templates`.
+  - `Model::Organization` — wired `query :page`, `query :pages`, `query :templates`.
+- **Page write layer (Phase B)**
+  - `Input::Page` — maps `PageInput` fields; owns `PAGE_FIELD_KEYS` as single source of truth.
+  - `Input::Page::Update` — maps `UpdatePageInput`; `from_model` builds the nested `page:`
+    sub-hash and always injects `patchVer` (a current `patchVer` must be fetched before update).
+  - `Input::Page::Archive`, `Input::Page::Unarchive`.
+  - `Mutation::Page::Update`/`Archive`/`Unarchive`, `Payload::Page::Update`/`Archive`/`Unarchive`
+    (all return a `PageUnion` item), `Builder::Page` (`update`/`archive`/`unarchive`),
+    `Ecoportal::API::GraphQL#page` top-level accessor.
+- **Fragment infrastructure**
+  - `Fragment::Pages` sub-namespace with `CommonPageUnion` — customer-facing fragment covering
+    stages, sections, all 20 data field types, actions, files, and emails. Parametric via
+    `$content`, `$only_content`, `$fields`.
+  - `FragmentDefinitions.register_namespace(klass)` — cross-namespace fragment discovery without
+    polluting the parent `fragments` hash.
+  - `BaseQuery#assemble_fragments` — resolves fragment spreads **recursively** (cycle-safe).
+- **`as_input` / diff pipeline**
+  - `Common::GraphQL::Model::AsInput#as_input(target_class:)` — delegates to a specified
+    `Input` subclass for field reshaping (e.g. `IdDiffInput` for array fields).
+  - `Logic::Input.from_model` — builds mutation input from a model diff; injects `patchVer`
+    and `clientMutationId`.
+  - `Input::ContractorEntity::Update.from_model` — reshapes array fields
+    (`associatedPeopleIds`, `leadContractorIds`) into `IdDiffInput` format.
+
+### Changed
+
+- **`Gemfile`** — override `graphlient` with the fork branch (GraphQL directives support).
+- **DataField dirty detection** — removed the per-field `@_dirty` flag in favour of
+  diff-based detection. `DataField` now uses a leaf-specific `DIFF_CLASS` (`LeafDiffService`)
+  so its `passarray` attributes are diffed inline instead of being stripped as cascaded keys.
+- **AI generator** — compatibility with the Anthropic Ruby SDK 1.x.
+
+### Fixed
+
+- **DataField array fields** (`Select`, `People`, `Checklist`, `ContractorEntities`,
+  `CrossReference`, `FileField`, `ImageGallery`) — were never reported dirty after a setter,
+  so `as_input` returned `nil`. `passarray` keys are *cascaded* attributes and the flat classic
+  diff strips them, expecting `diff_reduce` to re-add them by cascading into nested
+  `GraphQL::Model` children — but leaf-field arrays are plain hashes/strings, so they vanished.
+  Fixed with `DataField::LeafDiffService` (keeps cascaded keys) and by adding the missing
+  `array_ids` / `array_id_index` / `array_id_item` helpers to `HashDiffNesting`.
+- **Live AI specs** — resilient to SSL / auth failures in offline environments (skip instead of error).
+- **`HashDiffNesting#dig_path?`** — corrected to use `Hash#key?` rather than `respond_to?(:[])`,
+  preventing false positives on non-Hash objects.
+- **`DiffService#classic_diff`** — now returns a flat changed-prop hash (no `api_operation` /
+  `change_data` wrapper keys). `as_input` / `as_update` return `nil` when there are no changes.
+- **`assemble_fragments`** — fixed silent bug where a fragment referencing another fragment
+  (e.g. `PageFields → ...LocationNode`) would omit the referenced fragment from the query,
+  causing a server-side `unknown fragment` error.
+- **`Fragment.assemble`** — fixed silent bug where fragments defined in sub-namespaces
+  (e.g. `Fragment::Pages`) were never found, always returning empty.
+
+## [1.3.6] - 2026-06-05
+
+### Added
+
+- **`HttpClient#execute`**: new HTTP dispatch method — POSTs `{ query, variables, operationName }` as
+  JSON to `/api/:org_id/graphql` and returns the parsed response hash.
+- **`Common::GraphQL::ResponseError`**: typed exception raised when the GraphQL response body
+  contains an `errors` array.
+- **`Fragment.assemble(*syms)`**: class method that returns concatenated named fragment definition
+  strings for the given symbols, ready to append to a query document before dispatch.
+- **`Graphlient::Query#spread(name)`** _(graphlient fork)_: DSL helper that emits `...FragmentName`
+  in the query string. Replaces the `___Const` convention from graphql-client.
+- **`Client#to_query_string(&block)`** _(graphlient fork)_: builds a full GraphQL query document
+  from the DSL block and returns a `String` without touching Faraday or HTTP.
+
+### Changed
+
+- upgraded ecoportal upstream **gem** dependencies:
+  - `ecoportal-api`
+  - `ecoportal-api-v2`
+- **`BaseQuery#graphql_query`**: wired to the new dispatch path — builds query string via
+  `client.to_query_string`, appends needed named fragment strings, dispatches via
+  `client.http_client.execute`. Removes the graphql-client/Faraday dispatch path.
+- **`Common::GraphQL::Client`**: added `attr_accessor :http_client` to carry the HTTP dispatch
+  client alongside the DSL client.
+- **`Ecoportal::API::GraphQL#initialize`**: constructs and attaches a `Common::GraphQL::HttpClient`
+  instance to `@client.http_client`.
+- **Fragment strings**: all 7 fragment heredocs updated to use named fragment syntax
+  (e.g. `fragment Action on Action { ... }`), required for `Fragment.assemble` to emit
+  valid named fragment definitions.
+- **`FragmentDefinitions`**: stripped of `client.parse` and `namespace.const_set` — fragment
+  strings are now stored as plain Ruby strings. No longer depends on graphql-client for
+  fragment loading.
+- **Query/mutation blocks** (12 files): replaced `___Ecoportal__API__GraphQL__Fragment__X`
+  spread syntax with `spread :X` throughout all `default_block` and `default_payload_block` procs.
+
+### Fixed
+
+- **`HttpClient#base_request`**: added `request ||= HTTP` guard for the unmatched `@version` case
+  to prevent nil errors.
+- **`HttpClient#api_url`**: use `ENDPOINT_PATH` constant (`external/graphql`) consistently
+  instead of an inline hardcoded string.
+
+## [1.3.5] - 2026-05-26
+
+### Changed
+
+- Moved `graphql` endpoint to `external/graphql`
+- Missing env var (i.e. `ORG_ID`) will **raise** now an error (instead of just a print)
+
+## [1.3.4] - 2025-09-04
+
+### Added
+
+- Command execution result: **added** command doc when there's a `results` error.
+- Payload improvements:
+  - On `LocationsError.validationErrors`: fetch `property` property.
+  - On **results**, `Command` always fetch `__typename` and the other properties.
+
+### Changed
+
+- Changed base `error_doc`: **consistent property name**
+
+### Fixed
+
+- Correct fetch on `ok` (sometimes it is `null`: that doesn't mean failed).
+- **Consistent order** on `error?` and `error_doc`.
+- `Draft`
+  - **Overlapping** name `ConflictingIds` (vs `LocationsError.conflictingIds`)
+  - **Wrong** include on `FetchNested`
+
+## [1.3.3] - 2025-08-29
+
+### Added
+
+- Better error handling
+
+### Fixed
+
+- Unused parameter/variable `$includeArchivedNodes`
+
+## [1.3.2] - 2025-08-19
+
+### Added
+
+- `Mutation`: allow parameters other than **input**.
+- Location Structure `Draft` models
+- `Interface::LocationStructure::Nodes` for `LocationStructure` and `Draft::Structure`
+- `raw_response` as optional query parameter (for debugging)
+- `Logic::Input` (out of consistency)
+- Fragments:
+  - `LocationDraft`
+  - `LocationsError`
+- Query to include `draft` list when fetching an **RS**.
+- Location `Draft` queries:
+  - `Draft#byId`
+  - `Draft#create`
+  - `Draft#delete`
+  - `Draft#addCommands`
+  - `Draft#publish`
+  - `Draft#dropBadCommands`
+- Error tracking througout the payload models of location mutations
+
+### Changed
+
+- Upgrade dependency (`ecoportal-api` **gem**).
+- Moved rescue on fragment definition to `#define` itself.
+- `NodeInterface` moved to `Interface::LocationStructure::Node`
+- Code: Shorten namespace referral.
+- Swap to `Logic::BaseModel`
+- `Mutation` to introduce `:input` required parameter by using parent class.
+
+### Fixed
+
+- `QueryConnection`: bad code.
+- `conflictingIds` should be array.
+
+## [1.3.1] - 2025-06-11
+
+### Changed
+
+- upgraded gem dependencies
+- **Moded** `Ecoportal::API::GraphQL::Base::Model` to
+  - > `Ecoportal::API::GraphQL::BaseModel`
+- **Added** `Interface::LocationNode`
+- **Added** `Interface::BasePage`
+
+### Fixed
+
+- **Fragments**
+  - `Action` fragment to use `PageUnion` (**upgrade**)
+  - **Memoize** fragments.
+  - Add what fragment failed in the **error**.
+
+## [1.2.1] - 2025-05-16
+
+### Changed
+
+- upgrade `ecoportal-api` gem
+- upgrade `ecoportal-api-v2` gem
+
+## [1.1.1] - 2025-05-14
+
+### Added
+
+- `MemberChanges` helpers for `Base::ContractorEntity`
+- Custom **Diff** logic that can be used in GraphQL content:
+  - `Common::GraphQL::Model::Diffable::HashDiffNesting`
+    - Reused from `HashDiffPatch` (`ecoportal-api-v2`):
+      1. It does not use `patch_ver`, but rather just `id` property alone.
+      2. The _operation_ property has been renamed to `api_operation` (to ensure no collisions). And the operation types are symbols, and renamed to: `:delete`, `:update` and `:create`. This can show up to be useful when, for instance, reusing the output of `#as_update` to generate actual input objects (i.e. `#as_input`) that feed some GraphQL query.
+      3. The _data_ property has been renamed to `change_data`.
+      4. `Hash` **keys** are of type `Symbol`.
+  - `Common::GraphQL::Model::Diffable::DiffService`. In a GraphQL context, this aims to be able to implement a function called `#as_input` (equivalent to `#as_update`):
+      1. It uses the `HashDiffNesting` helpers.
+      2. It has capability to `ignore` certain keys.
+      3. It can calculate **diff** excluding nested models (i.e. those that are `root?` and, therefore, not part of the changed target model). This functionality is an optimization to `cascaded_callbacks` throughout the nested models.
+
+### Changed
+
+- `Common::GraphQL::Model::Diffable` by using `Diffable::DiffService` (with `cascaded_callbacks` implementation).
+  - `#as_update`
+  - `#dirty?`
+- upgraded `ecoportal-api` gem
+- updraded `ecoportal-api-v2` gem
+
+## [0.4.7] - 2025-04-02
+
+### Added
+
+- `page.id` to Action linked resources.
+
+## [0.4.6] - 2025-04-02
+
+### Added
+
+- `Ecoportal::API::GraphQL::Logic::QueryConnection`
+  - **Require** `default_connection_block` to child classes
+  - This aims to **not** having have client code having to define the block for `#each`
+
+### Changed
+
+- upgraded `ecoportal-api` gem
+- upgraded `ecoportal-api-v2` gem
+
+## [0.4.5] - 2025-03-14
+
+### Added
+
+- Query `actionCategories`
+- Mutation **create** `Action`
+
+### Changed
+
+- `Action` model to have `locations` (**RS** upgrade)
+
+## [0.4.4] - 2025-02-23
+
+### Changed
+
+- Upgraded `ecoportal-api` gem (maintanance)
+- Upgraded `ecoportal-api-v2` gem (to provision `root!` class method)
+- Defined some models that hand on their own as `root!`
+- Refactored `Base::Model` by moving its loggic to `Common::GraphQL`
+
+### Fixed
+
+- `Ecoportal::API::Common::GraphQL::HashHelpers`
+  - Truly make the iterator generic
+
+## [0.4.3] - 2024-11-21
+
+### Changed
+
+- upgrade gems
+  - `ecoportal-api`
+  - `ecoportal-api-v2`
+- `Ecoportal::API::Common::GraphQL::HttpClient.new` ceased to default `version` to `v1` (now it defaults to `nil`)
+
+## [0.4.2] - 2024-10-01
+
+### Changed
+
+- upgrade gems
+  - `ecoportal-api-v2`
+- add explicit dependency onto `ecoportal-api` gem (client)
+
+## [0.4.1] - 2024-08-09
+
+### Added
+
+- `ContractorEntity` added field `externalId`
+
+### Changed
+
+- gem upgrade `ecoportal-api-v2`
+
+## [0.4.0] - 2024-08-01
+
+### Changed
+
+- require `ruby 3`
+
+## [0.3.18] - 2024-05-16
+
+### Fixed
+
+- `Ecoportal::API::GraphQL::Payload::LocationStructure::CommandExecutionResult`
+  - Error is nullable
+
+## [0.3.17] - 2024-05-14
+
+### Fixed
+
+- `field_name` should add up to the path
+
+## [0.3.16] - 2024-04-29
+
+### Added
+
+- Exposed `graphql` `ContractorEntity` `destroy`
+
+### Fixed
+
+- incorrect loading
+
+### Changed
+
+- Input for ContractorEntity create moved as `update` (as it wasn't correct)
+
+## [0.3.15] - 2024-04-13
+
+### Added
+
+- `Ecoportal::API::GraphQL::Logic::BaseQuery`
+  - `::base_path` class instance var.
+- query to retrieve `currentOrganization.classifications`
+
+### Fixed
+
+- upgraded `ecoportal-api-v2` gem
+
+## [0.3.14] - 2024-03-13
+
+### Added
+
+- some benchmarking on
+  1. core graphql base `query`
+- `#parent_id` to location node model
+
+### Changed
+
+- upgraded `ecoportal-v2-api` gem
+
+### Fixed
+
+- Optimized `treeify` and locations structure class
+
+## [0.3.13] - 2024-02-03
+
+### Changed
+
+- upgrade `ecoportal-api-v2`
+
+## [0.3.12] - 2024-01-27
+
+### Added
+
+- Exposed `graphql` `Action` `update` and get a single `action`
+
+## [0.3.11] - 2023-09-19
+
+### Added
+
+- Exposed `graphql` `ContractorEntity` `create` and `update`
+
+## [0.3.10] - 2023-08-12
+
+### Fixed
+
+- `Ecopotal::API::GraphQL::Query::LocationStructure`
+  - `query` in basic_block missed an explicitly declared parameter.
+
+## [0.3.9] - 2023-08-03
+
+### Added
+
+- `Ecoportal::API::GraphQL::Logic::BaseQuery`
+  - Added support for **default** values.
+
+## [0.3.8] - 2023-07-18
+
+### Added
+
+- Integration for archiving actions.
+- `LocationNodeInterface` -> support for `classifications`
+- `Treeify` to dump more data per node (classifications)
+
+### Fixed
+
+- Silenced waning messages when redefining `Fragment`s
+
+## [0.3.7] - 2023-05-23
+
+### Fixed
+
+- `Ecoportal::API::Common::GraphQL::Client` adjusted `read_timeout` and `write_timeout` to `90` seconds.
+
+## [0.3.6] - 2023-04-17
+
+### Changed
+
+- Softened max version of **gem** dependencies
+
+### Fixed
+
+- `Ecoportal::API::GraphQL::Fragment#define` was not removing previous constants
+  - Changed check method to be `::const_defined?`
+
+## [0.3.5] - 2023-04-03
+
+### Fixed
+
+- `Ecoportal::API::GraphQL::Helpers::LocationsTree#treeify`
+  - Make it real id-case-insensitive (parents in lower case were being missed due to this)
+
+## [0.3.4] - 2023-04-03
+
+### Added
+
+- `Ecoportal::API::Common::GraphQL::AuthService`
+  - `#session_token` added **token auto-renew** functionality (when token expires in less than 90 minutes)
+  - `#session_token_renewed`
+
+### Fixed
+
+- Enabled to specify `host` (other than `live.ecoportal.com`) by the user
+
+## [0.3.3] - 2023-04-02
+
+### Fixed
+
+- `Ecoportal::API::GraphQL::Base::LocationNode` **added** attribute `archivedToken`
+
+## [0.3.2] - 2023-04-02
+
+### Changed
+
+- `Ecoportal::API::GraphQL::Helpers::LocationsTree#treeify` added support for `archived_token`
+
+## [0.3.1] - 2023-03-09
+
+### Changed
+
+- Upgraded core gem dependency `ecoportal-api-v2`
+
+## [0.2.3] - 2023-02-27
+
+### Fixed
+
+- Typo in tests LocationsStructures... should read `locationStructures`
+
+## [0.2.2] - 2023-02-24
+
+### Fixed
+
+- Build gem correctly
+
+## [0.2.1] - 2023-02-24
+
+### Changed
+
+- Migrate from TagTrees to **reporting structures** (breaking change)
+
+### Added
+
+- Basics for reporting structure mutations
+
+## [0.1.11] - 2022-11-29
+
+### Added
+
+- `Ecoportal::API::GraphQL::Base::Mutation`
+- Added `createContractorEntity`
+
+### Changed
+
+- **upgraded** `graphlient` gem dependency (support for framents)
+  - removed patch in this gem
+- Slight internal refactor of `Ecoportal::API::GraphQL::Base::Query`
+- Upgraded `ecoportal-api-v2` **gem** dependency
+
+## [0.1.10] - 2022-09-29
+
+### Changed
+
+- **upgraded** `ecoportal-api-v2` gem dependency
+
+### Fixed
+
+- Remove debugging message
+
+## [0.1.9] - 2022-09-26
+
+### Added
+
+- `Ecoportal::API::GraphQL::Query::TagTree`
+
+### Changed
+
+- **upgraded** `ecoportal-api-v2` gem dependency
+- added `Ecoportal::API::Common::GraphQL::QueryIntegration`
+  - restructured `Ecoportal::API::GraphQL::Model::Organization` class
+- **Patch** on `Graphlient::Query` for fragments support (**pull request**: <https://github.com/ashkan18/graphlient/pull/94>)
+
+## [0.1.8] - 2022-09-23
+
+### Added
+
+- `currentOrganization.tagTrees` query
+
+### Changed
+
+- **upgraded** `ecoportal-api-v2` gem dependency
+- Restructured the `Query` inheritance chain to make things simpler
+
+## [0.1.6] - 2022-09-19
+
+### Fixed
+
+- Call to **private** method `remove_const` in `Ecoportal::API::GraphQL::Fragment#define`
+
+## [0.1.5] - 2022-09-19
+
+### Added
+
+- Patch `GraphQL::Query#append_node` so we can use Fragments in blocks using `___` as start of the constant, and `__` for namespace separator
+  - Issue/feature request: <https://github.com/ashkan18/graphlient/issues/93>
+- `Ecoportal::API::GraphQL::Fragment#define` provided that client scripts can create their own fragments in their own namespace
+  - Exposed `Ecoportal::API::GraphQL#fragments`
+  - It will always (re)define in the `Fragment` root namespace
+
+## [0.1.4] - 2022-09-16
+
+### Fixed
+
+- Able to inject connection block to `each`
+- Error handling delegated to parent class (`QueryConnection`)
+- Retrieve `id` on elements of `Array`
+
+## [0.1.3] - 2022-09-15
+
+### Fixed
+
+- Fixed circular reference to `org_id` in `Ecoportal::API::Common::GraphQL::Client`
+
+## [0.1.2] - 2022-09-15
+
+### Changed
+
+- `Ecoportal::API::GraphQL` addded `email` and `pass` parameters on initialization
+  - This allows for integration in some client lib
+
+## [0.1.0] - 2022-09-15
+
+### Added
+
+- First commit with some basic structure