ecoportal-api-graphql 2.0.0 → 3.0.0

data/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2022 ecoPortal
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2022 ecoPortal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.gem.md

@@ -0,0 +1,53 @@
+# ecoportal-api-graphql
+
+A Ruby client for the ecoPortal GraphQL API: typed models for pages, templates, data fields and
+registers, query and mutation helpers, and the workflow command bus for granular template edits.
+
+This is the README shipped inside the published gem. The source repository keeps its own
+developer README.
+
+## Install
+
+```ruby
+gem 'ecoportal-api-graphql', require: %w[ecoportal/api-graphql]
+```
+
+```
+$ bundle
+# or: $ gem install ecoportal-api-graphql
+```
+
+## Requirements
+
+| | version |
+|---|---|
+| Ruby | `>= 3.2.2` |
+| `ecoportal-api` | `~> 0.10, >= 0.10.17` |
+| `ecoportal-api-v2` | `~> 3.3, >= 3.3.5` |
+| `graphlient` | `>= 0.9.0, < 0.10` |
+
+## Example: load and edit a template
+
+```ruby
+api      = Ecoportal::API::GraphQL.new(email: ..., pass: ..., org_id: ...)
+template = Ecoportal::API::GraphQL::Model::Template.load(api, id: template_page_id)
+template.fields.each { |f| f.label = "#{f.label} (reviewed)" }
+template.save!(api, simulate: false)   # simulate: true is the default -- inspect first
+```
+
+`save!` simulates by default: it reports the commands it would send without writing anything.
+Pass `simulate: false` to apply them.
+
+## Optional extensions
+
+Some capabilities are distributed separately as optional extensions and are not part of this
+gem. The gem works fully without them; when an extension is installed, it is picked up
+automatically.
+
+## Changes
+
+See `CHANGELOG.md`, shipped alongside this file.
+
+## Licence
+
+MIT -- see `LICENSE`.

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

@@ -1,115 +1,115 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        module AuthService
-          DEFAULT_SERVER  = 'live.ecoportal.com'.freeze
-          TOKEN_AUTORENEW = 90 # minutes
-
-          module InstanceMethods
-            def session_token(host: server, auto_renew: true)
-              session_token_data(host: host).then do |body|
-                next unless body
-
-                if auto_renew && token_renew?(body['expires_in'])
-                  session_token_renewed(
-                    host:          host,
-                    refresh_token: body['refresh_token']
-                  )
-                else
-                  body['access_token']
-                end
-              end
-            end
-
-            def session_token_renewed(host: server, refresh_token: nil)
-              unless refresh_token
-                return unless (body = session_token_data(host: host))
-                return unless (refresh_token = body['resfresh_token'])
-              end
-
-              session_refresh_token_data(
-                host:          host,
-                refresh_token: refresh_token
-              ).then do |bdy|
-                bdy['access_token'] if bdy
-              end
-            end
-
-            private
-
-            def session_token_data(host: server)
-              auth_http_client(host: host).post(
-                '/oauth/token',
-                data: {
-                  'grant_type' => 'password',
-                  'email'      => user_email,
-                  'password'   => user_pass
-                }
-              ).then do |response|
-                next response.body if response.success?
-              end
-            end
-
-            def session_refresh_token_data(refresh_token:, host: server)
-              auth_http_client(host: host).post(
-                '/oauth/token',
-                data: {
-                  'grant_type'    => 'refresh_token',
-                  'refresh_token' => refresh_token
-                }
-              ).then do |response|
-                next response.body if response.success?
-              end
-            end
-
-            def token_renew?(seconds)
-              (TOKEN_AUTORENEW * 60) > seconds
-            end
-
-            def auth_http_client(host: server)
-              @auth_http_client ||= Ecoportal::API::Common::GraphQL::HttpClient.new(
-                host:    host,
-                version: 'http'
-              )
-            end
-
-            def user_email
-              @user_email || fetch_env_required('USER_EMAIL')
-            end
-
-            def user_pass
-              @user_pass || fetch_env_required('USER_PASS')
-            end
-
-            def server(default = DEFAULT_SERVER)
-              ENV['SERVER'] || default
-            end
-
-            def fetch_env_required(name)
-              raise "Missing ENV '#{name}'" unless ENV.key?(name)
-              ENV[name]
-            end
-
-            def abort(msg)
-              puts msg
-              exit(1)
-            end
-          end
-
-          module ClassMethods
-          end
-
-          class << self
-            include InstanceMethods
-
-            def included(base)
-              base.send(:include, InstanceMethods)
-              base.extend(ClassMethods)
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        module AuthService
+          DEFAULT_SERVER  = 'live.ecoportal.com'.freeze
+          TOKEN_AUTORENEW = 90 # minutes
+
+          module InstanceMethods
+            def session_token(host: server, auto_renew: true)
+              session_token_data(host: host).then do |body|
+                next unless body
+
+                if auto_renew && token_renew?(body['expires_in'])
+                  session_token_renewed(
+                    host:          host,
+                    refresh_token: body['refresh_token']
+                  )
+                else
+                  body['access_token']
+                end
+              end
+            end
+
+            def session_token_renewed(host: server, refresh_token: nil)
+              unless refresh_token
+                return unless (body = session_token_data(host: host))
+                return unless (refresh_token = body['refresh_token'])
+              end
+
+              session_refresh_token_data(
+                host:          host,
+                refresh_token: refresh_token
+              ).then do |bdy|
+                bdy['access_token'] if bdy
+              end
+            end
+
+            private
+
+            def session_token_data(host: server)
+              auth_http_client(host: host).post(
+                '/oauth/token',
+                data: {
+                  'grant_type' => 'password',
+                  'email'      => user_email,
+                  'password'   => user_pass
+                }
+              ).then do |response|
+                next response.body if response.success?
+              end
+            end
+
+            def session_refresh_token_data(refresh_token:, host: server)
+              auth_http_client(host: host).post(
+                '/oauth/token',
+                data: {
+                  'grant_type'    => 'refresh_token',
+                  'refresh_token' => refresh_token
+                }
+              ).then do |response|
+                next response.body if response.success?
+              end
+            end
+
+            def token_renew?(seconds)
+              (TOKEN_AUTORENEW * 60) > seconds
+            end
+
+            def auth_http_client(host: server)
+              @auth_http_client ||= Ecoportal::API::Common::GraphQL::HttpClient.new(
+                host:    host,
+                version: 'http'
+              )
+            end
+
+            def user_email
+              @user_email || fetch_env_required('USER_EMAIL')
+            end
+
+            def user_pass
+              @user_pass || fetch_env_required('USER_PASS')
+            end
+
+            def server(default = DEFAULT_SERVER)
+              ENV['SERVER'] || default
+            end
+
+            def fetch_env_required(name)
+              raise "Missing ENV '#{name}'" unless ENV.key?(name)
+              ENV[name]
+            end
+
+            def abort(msg)
+              puts msg
+              exit(1)
+            end
+          end
+
+          module ClassMethods
+          end
+
+          class << self
+            include InstanceMethods
+
+            def included(base)
+              base.send(:include, InstanceMethods)
+              base.extend(ClassMethods)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,46 +1,46 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        module ClassHelpers
-          module InstanceMethods
-            def becomes(klass)
-              klass.new.tap do |becoming|
-                instance_variables.each do |var|
-                  becoming.instance_variable_set(
-                    var,
-                    instance_variable_get(var)
-                  )
-                end
-              end
-            end
-
-            def becomes_parent_class
-              becomes(self.class.superclass)
-            end
-          end
-
-          module ClassMethods
-            include Ecoportal::API::Common::Content::ClassHelpers
-
-            def const?(value)
-              begin
-                const_get(value)
-              rescue NameError
-                return false
-              end
-              true
-            end
-          end
-
-          class << self
-            def included(base)
-              base.send(:include, InstanceMethods)
-              base.extend(ClassMethods)
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        module ClassHelpers
+          module InstanceMethods
+            def becomes(klass)
+              klass.new.tap do |becoming|
+                instance_variables.each do |var|
+                  becoming.instance_variable_set(
+                    var,
+                    instance_variable_get(var)
+                  )
+                end
+              end
+            end
+
+            def becomes_parent_class
+              becomes(self.class.superclass)
+            end
+          end
+
+          module ClassMethods
+            include Ecoportal::API::Common::Content::ClassHelpers
+
+            def const?(value)
+              begin
+                const_get(value)
+              rescue NameError
+                return false
+              end
+              true
+            end
+          end
+
+          class << self
+            def included(base)
+              base.send(:include, InstanceMethods)
+              base.extend(ClassMethods)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,69 +1,107 @@
-require 'graphlient'
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        class Client < ::Graphlient::Client
-          ENDPOINT_PATH = 'external/graphql'.freeze
-
-          attr_accessor :host, :http_client
-
-          READ_TIMEOUT  = 90
-          WRITE_TIMEOUT = 90
-
-          include Ecoportal::API::Common::GraphQL::AuthService
-
-          def initialize(
-            email:       nil,
-            pass:        nil,
-            org_id:      self.org_id,
-            host:        server,
-            schema_path: host,
-            no_schema:   false
-          )
-            @org_id      = org_id
-            @host        = host
-            @no_schema   = no_schema
-            @user_email  = email
-            @user_pass   = pass
-
-            puts "Configuring GraphQL Client onto '#{url}'"
-
-            super(
-              url,
-              headers:      {
-                'Authorization' => "Bearer #{session_token(host: host)}"
-              },
-              http_options: {
-                read_timeout:  READ_TIMEOUT,
-                write_timeout: WRITE_TIMEOUT
-              }.tap do |options|
-                options.merge!(schema_path: schema_path) unless @no_schema
-              end
-            )
-          end
-
-          def new(org_id: self.org_id, host: self.host, schema_path: host, no_schema: @no_schema)
-            self.class.new(
-              org_id:      org_id,
-              host:        host,
-              schema_path: schema_path,
-              no_schema:   no_schema
-            )
-          end
-
-          def org_id
-            @org_id || fetch_env_required('ORGANIZATION_ID')
-          end
-
-          private
-
-          def url
-            base_url = Ecoportal::API::Common::GraphQL::HttpClient.base_url(host)
-            "#{base_url}/api/#{org_id}/#{ENDPOINT_PATH}"
-          end
-        end
-      end
-    end
-  end
-end
+require 'graphlient'
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        class Client < ::Graphlient::Client
+          ENDPOINT_PATH = 'external/graphql'.freeze
+
+          attr_accessor :host, :http_client
+
+          READ_TIMEOUT  = 90
+          WRITE_TIMEOUT = 90
+
+          include Ecoportal::API::Common::GraphQL::AuthService
+
+          def initialize(
+            email:       nil,
+            pass:        nil,
+            org_id:      self.org_id,
+            host:        server,
+            schema_path: host,
+            no_schema:   false
+          )
+            @org_id      = org_id
+            @host        = host
+            @no_schema   = no_schema
+            @user_email  = email
+            @user_pass   = pass
+
+            puts "Configuring GraphQL Client onto '#{url}'"
+
+            super(
+              url,
+              headers:      {
+                'Authorization' => "Bearer #{session_token(host: host)}"
+              },
+              http_options: {
+                read_timeout:  READ_TIMEOUT,
+                write_timeout: WRITE_TIMEOUT
+              }.tap do |options|
+                options.merge!(schema_path: schema_path) unless @no_schema
+              end
+            )
+          end
+
+          def new(org_id: self.org_id, host: self.host, schema_path: host, no_schema: @no_schema)
+            self.class.new(
+              org_id:      org_id,
+              host:        host,
+              schema_path: schema_path,
+              no_schema:   no_schema
+            )
+          end
+
+          def org_id
+            @org_id || fetch_env_required('ORGANIZATION_ID')
+          end
+
+          # Graphlient/graphql-client build the client-side schema from the server's raw
+          # introspection JSON (GraphQL::Schema.from_introspection -> GraphQL::Schema::Loader).
+          # That loader defines one GraphQL::Schema::InputObject subclass per INPUT_OBJECT type,
+          # but it never calls `has_no_arguments(true)` on the ones whose `inputFields` came back
+          # empty. graphql-ruby then warns (and, in a future version, raises) the first time
+          # anything asks such a type for its arguments -- which happens whenever this schema is
+          # re-serialized (e.g. `schema.to_json`/`to_definition`, as the `-graphql-schema` use
+          # case in eco-helpers does). The live server never emits this warning because its own
+          # schema classes are defined directly in Ruby with real argument lists (or with
+          # `has_no_arguments(true)` already set) -- it is only the client-side schema, rebuilt
+          # purely from introspection data, that loses that annotation.
+          #
+          # Patching the built classes here (rather than pre-processing the introspection JSON)
+          # keeps the schema's shape untouched and uses graphql-ruby's own documented escape
+          # hatch for this exact situation.
+          def schema
+            mark_argumentless_input_objects!(super)
+          end
+
+          private
+
+          def url
+            base_url = Ecoportal::API::Common::GraphQL::HttpClient.base_url(host)
+            "#{base_url}/api/#{org_id}/#{ENDPOINT_PATH}"
+          end
+
+          def mark_argumentless_input_objects!(loaded_schema)
+            return loaded_schema if @argumentless_input_objects_marked
+
+            graphql_schema_types(loaded_schema).each_value do |type|
+              next unless type.respond_to?(:kind) && type.kind.input_object?
+              next unless type.respond_to?(:has_no_arguments) && type.respond_to?(:any_arguments?)
+
+              type.has_no_arguments(true) unless type.any_arguments?
+            end
+            @argumentless_input_objects_marked = true
+
+            loaded_schema
+          end
+
+          def graphql_schema_types(loaded_schema)
+            target = loaded_schema.respond_to?(:graphql_schema) ? loaded_schema.graphql_schema : loaded_schema
+            target.types
+          end
+        end
+      end
+    end
+  end
+end