haveapi 0.29.9 → 0.30.0

data/lib/haveapi/client_examples/js_client.rb

@@ -1,164 +1,208 @@
-require 'haveapi/client_example'
+require 'haveapi/client_examples/dynamic_helpers'
 
 module HaveAPI::ClientExamples
   class JsClient < HaveAPI::ClientExample
-    label 'JavaScript'
+    include DynamicHelpers
+
+    label 'JavaScript (callback)'
+    id 'javascript-callback'
     code :javascript
     order 10
 
-    def init
-      <<~END
-        import HaveAPI from 'haveapi-client'
-
-        var api = new HaveAPI.Client("#{base_url}", {version: "#{version}"});
-      END
+    def asynchronous?
+      false
     end
 
-    def auth(method, desc)
-      case method
-      when :basic
-        <<~END
-          #{init}
-
-          api.authenticate("basic", {
-            user: "user",
-            password: "secret"
-          }, function (client, status) {
-            console.log("Authenticated?", status);
-          });
-        END
+    def typescript?
+      false
+    end
 
-      when :token
-        <<~END
-          #{init}
+    def js_literal(value)
+      value = json_data(value)
+      case value
+      when Hash
+        "{#{value.map { |key, entry| "[#{JSON.generate(key)}]: #{js_literal(entry)}" }.join(', ')}}"
+      when Array
+        "[#{value.map { |entry| js_literal(entry) }.join(', ')}]"
+      when Integer
+        raise Unsupported, 'This sample contains an integer outside JavaScript exact precision.' if value.abs > 9_007_199_254_740_991
+
+        value.to_s
+      else
+        JSON.generate(value).gsub("\u2028", '\\u2028').gsub("\u2029", '\\u2029')
+      end
+    end
 
-          // Request a new token
-          api.authenticate("token", {
-            #{auth_token_credentials(desc).map { |k, v| "#{k}: \"#{v}\"" }.join(",\n  ")}
-          }, function (client, status) {
-            console.log("Authenticated?", status);
+    def client_name
+      asynchronous? ? 'AsyncClient' : 'CallbackClient'
+    end
 
-            if (status)
-              console.log("Token is", client.authProvider.token);
-          });
+    def env_helper
+      type = typescript? ? ': string' : ''
+      <<~JS
+        function credential(name#{type})#{type} {
+          const value = env[name];
+          if (value === undefined) throw new Error("Set " + name + " before running this example");
+          return value;
+        }
+      JS
+    end
 
-          // Use an existing token
-          api.authenticate("token", {
-            token: "qwertyuiop..."
-          }, function (client, status) {
-            console.log("Authenticated?", status);
+    def program(body, authentication: nil)
+      imports = "import { #{client_name}#{', AsyncError' if asynchronous?} } from \"haveapi-client\";\n"
+      imports << "import { env } from \"node:process\";\n\n#{env_helper}\n" if authentication
+      declaration = "const api = new #{client_name}(#{js_literal(api_base)}, {version: #{js_literal(api_version)}});\n"
+      if asynchronous?
+        <<~JS
+          #{imports}
+          async function main()#{': Promise<void>' if typescript?} {
+          #{indent(declaration)}  try {
+          #{indent(authentication || "await api.setup();\n", 4)}#{indent(body, 4)}  } catch (error) {
+              if (error instanceof AsyncError) {
+                console.error(error.kind, error.message, error.errors);
+              } else {
+                throw error;
+              }
+            }
+          }
+          main().catch(error => console.error(error));
+        JS
+      else
+        <<~JS
+          #{imports}
+          #{declaration}
+          #{authentication || 'api.setup('}(client, ready) => {
+            if (!ready) {
+              console.error("Discovery or authentication failed");
+              return;
+            }
+            try {
+          #{indent(body, 4)}  } catch (error) {
+              console.error(error);
+            }
           });
-        END
-
-      when :oauth2
-        <<~END
-          #{init}
-          // The JavaScript client must be configured with OAuth2 access token, it does not
-          // support the authorization procedure to obtain a new access token.
-          var accessToken = {
-            access_token: "the access token"
-          };
-
-          // The client is authenticated immediately, no need for a callback
-          api.authenticate("oauth2", {access_token: accessToken});
-        END
+        JS
       end
     end
 
-    def example(sample)
-      args = []
-
-      args.concat(sample[:path_params]) if sample[:path_params]
+    def init
+      code_result { program("console.log(\"Discovery complete\");\n") }
+    end
 
-      if sample[:request] && !sample[:request].empty?
-        args << JSON.pretty_generate(sample[:request])
+    def action_authentication
+      return nil unless field(current_action, :auth)
+
+      method = %i[token basic oauth2].find { |name| supported_auth?(name) }
+      raise Unsupported, 'This action requires an authentication provider unsupported by this client.' unless method
+
+      options = {
+        token: '{token: credential("HAVEAPI_TOKEN")}',
+        basic: '{user: credential("HAVEAPI_USER"), password: credential("HAVEAPI_PASSWORD")}',
+        oauth2: '{access_token: {access_token: credential("HAVEAPI_ACCESS_TOKEN")}}'
+      }.fetch(method)
+      if asynchronous?
+        "await api.authenticate(#{js_literal(method.to_s)}, #{options});\n"
+      else
+        "api.authenticate(#{js_literal(method.to_s)}, #{options}, "
       end
+    end
 
-      out = "#{init}\n"
-      out << "api.#{resource_path.join('.')}.#{action_name}"
-      out << '('
-      out << "#{args.join(', ')}, " unless args.empty?
-
-      callback = "function (client, reply) {\n"
-      callback << "  console.log('Response', reply);\n"
-
-      callback << if sample[:status]
-                    response(sample)
-
-                  else
-                    error(sample)
+    def auth(method, description)
+      return limitation('This authentication provider is not advertised or supported by this client.') unless supported_auth?(method)
+
+      code_result do
+        options = case method.to_sym
+                  when :basic
+                    '{user: credential("HAVEAPI_USER"), password: credential("HAVEAPI_PASSWORD")}'
+                  when :token
+                    if token_login_fields(description).empty?
+                      '{token: credential("HAVEAPI_TOKEN")}'
+                    else
+                      "env.HAVEAPI_TOKEN !== undefined ? {token: credential(\"HAVEAPI_TOKEN\")} : #{token_login_options(description)}"
+                    end
+                  when :oauth2
+                    '{access_token: {access_token: credential("HAVEAPI_ACCESS_TOKEN")}}'
                   end
+        authentication = if asynchronous?
+                           "await api.authenticate(#{js_literal(method.to_s)}, #{options});\n"
+                         else
+                           "api.authenticate(#{js_literal(method.to_s)}, #{options}, "
+                         end
+        source = program("console.log(\"Authenticated\");\n", authentication:)
+        if method.to_sym == :oauth2
+          source = "// Use an existing access token; this client does not run an OAuth authorization flow.\n#{source}"
+        elsif method.to_sym == :token && !token_login_fields(description).empty?
+          source = "// Set HAVEAPI_TOKEN, or use login fields; HAVEAPI_AUTH_* and HAVEAPI_CHALLENGE_* contain JSON values.\n#{source}"
+        end
+        source
+      end
+    end
 
-      callback << '}'
-
-      out << callback.strip
-      out << ');'
-      out
+    def token_login_options(description)
+      fields = token_login_fields(description).map do |name, _|
+        "[#{js_literal(name.to_s)}]: JSON.parse(credential(#{js_literal("HAVEAPI_AUTH_#{name}")}))"
+      end
+      challenge = asynchronous? ? 'onChallenge' : 'callback'
+      annotation = typescript? ? ': Record<string, unknown>' : ''
+      fields << <<~JS.strip
+        #{challenge}: (action, parameters) => {
+          const input#{annotation} = Object.create(null);
+          for (const name of Object.keys(parameters)) {
+            if (name !== "token") input[name] = JSON.parse(credential("HAVEAPI_CHALLENGE_" + name));
+          }
+          return input;
+        }
+      JS
+      "{#{fields.join(",\n")}}"
     end
 
-    def response(sample)
-      out = ''
-
-      case action[:output][:layout]
-      when :hash
-        out << "  // reply is an instance of HaveAPI.Client.Response\n"
-        out << "  // reply.response() returns an object with output parameters:\n"
-        out << JSON.pretty_generate(sample[:response] || {}).split("\n").map do |v|
-          "  // #{v}"
-        end.join("\n")
-        out << "\n"
-
-      when :hash_list
-        out << "  // reply is an instance of HaveAPI.Client.Response\n"
-        out << "  // reply.response() returns an array of objects:\n"
-        out << JSON.pretty_generate(sample[:response] || []).split("\n").map do |v|
-          "  // #{v}"
-        end.join("\n")
-        out << "\n"
-
-      when :object
-        out << "  // reply is an instance of HaveAPI.Client.ResourceInstance\n"
-
-        (sample[:response] || {}).each do |pn, pv|
-          param = action[:output][:parameters][pn]
-
-          if param[:type] == 'Resource'
-            out << "  // reply.#{pn} = HaveAPI.Client.ResourceInstance("
-            out << "resource: #{param[:resource].join('.')}, "
-
-            out << if pv.is_a?(::Hash)
-                     pv.map { |k, v| "#{k}: #{PP.pp(v, '').strip}" }.join(', ')
-                   else
-                     "id: #{pv}"
-                   end
-
-            out << ")\n"
-
-          elsif param[:type] == 'Custom' && (pv.is_a?(::Hash) || pv.is_a?(::Array))
-            json = JSON.pretty_generate(pv).split("\n").map do |v|
-              "  // #{v}"
-            end.join("\n")
-
-            out << "  // reply.#{pn} = #{json}"
-
-          else
-            out << "  // reply.#{pn} = #{PP.pp(pv, '')}"
-          end
+    def example(sample)
+      code_result do
+        path, request = structured_sample(sample)
+        if request.is_a?(Array)
+          raise Unsupported, 'This JavaScript client accepts object input only; list input cannot be represented without dropping values.'
+        end
+        if !request.nil? && !request.is_a?(Hash)
+          raise Unsupported, 'This JavaScript client requires object input.'
+        end
+        if !asynchronous? && field(field(current_action, :input), :parameters, {}).keys.any? { |name| %w[hasOwnProperty __proto__].include?(name.to_s) }
+          raise Unsupported, 'This callback client cannot safely represent this input parameter name.'
+        end
+        if request && %w[GET OPTIONS].include?(field(current_action, :method).to_s.upcase) && request.values.any? { |value| value.is_a?(Hash) || value.is_a?(Array) }
+          raise Unsupported, 'This JavaScript client cannot preserve nested values in query input.'
         end
 
-      when :object_list
-        out << "  // reply is an instance of HaveAPI.Client.ResourceInstanceList\n"
+        args = path.values.map { |value| js_literal(value) }
+        if asynchronous?
+          resource = current_resource_path.each_with_index.map do |name, index|
+            "#{'api' if index == 0}.resource(#{js_literal(name)})"
+          end.join
+          options = request.nil? ? [] : ["{params: #{js_literal(request)}}"]
+          body = "const result = await #{resource}.action(#{js_literal(current_action_name)})(#{(args + options).join(', ')});\n"
+          body << "console.log(result.value);\nconsole.log(result.response.meta);\n"
+          if field(current_action, :blocking)
+            body << "// Request success alone does not establish operation completion.\n"
+            body << "const completed = await api.waitForCompletion(result, {timeoutMs: 300000});\nconsole.log(completed.state);\n"
+          end
+        else
+          body = "const resource = CallbackClient.findResource(client, #{js_literal(current_resource_path)});\n"
+          body << "const action = CallbackClient.findAction(resource, #{js_literal(current_action_name)});\n"
+          options = request.nil? ? '' : "params: #{js_literal(request)},\n"
+          options << <<~JS
+            onReply: (owner, reply) => {
+              if (!reply.isOk()) {
+                console.error(reply.message(), reply.envelope.errors);
+                return;
+              }
+              console.log(reply.response());
+              console.log(reply.meta());
+            }
+          JS
+          body << "action.directInvoke(#{(args + ["{\n#{indent(options)}}"]).join(', ')});\n"
+          body << "// This prints the initial response; use its action-state metadata to monitor completion.\n" if field(current_action, :blocking)
+        end
+        program(body, authentication: action_authentication)
       end
-
-      out
-    end
-
-    def error(sample)
-      out = ''
-      out << "  // reply.isOk() returns false\n"
-      out << "  // reply.message() returns the error message\n"
-      out << "  // reply.envelope.errors contains parameter errors\n"
-      out
     end
   end
 end

data/lib/haveapi/client_examples/python_async_client.rb

@@ -0,0 +1,14 @@
+require 'haveapi/client_examples/python_client'
+
+module HaveAPI::ClientExamples
+  class PythonAsyncClient < PythonClient
+    label 'Python (async)'
+    id 'python-async'
+    code :python
+    order 15
+
+    def asynchronous?
+      true
+    end
+  end
+end

data/lib/haveapi/client_examples/python_client.rb

@@ -0,0 +1,172 @@
+require 'haveapi/client_examples/dynamic_helpers'
+
+module HaveAPI::ClientExamples
+  class PythonClient < HaveAPI::ClientExample
+    include DynamicHelpers
+
+    label 'Python (sync)'
+    id 'python-sync'
+    code :python
+    order 14
+
+    def asynchronous?
+      false
+    end
+
+    def python_literal(value)
+      value = json_data(value)
+      case value
+      when Hash
+        "{#{value.map { |key, entry| "#{JSON.generate(key)}: #{python_literal(entry)}" }.join(', ')}}"
+      when Array
+        "[#{value.map { |entry| python_literal(entry) }.join(', ')}]"
+      when TrueClass then 'True'
+      when FalseClass then 'False'
+      when NilClass then 'None'
+      else JSON.generate(value)
+      end
+    end
+
+    def client_name
+      asynchronous? ? 'AsyncClient' : 'Client'
+    end
+
+    def await_prefix
+      asynchronous? ? 'await ' : ''
+    end
+
+    def program(body, imports: [], auth: nil)
+      package_imports = ([client_name, 'ActionError', 'HaveAPIError'] + imports).uniq.join(', ')
+      source = "import os\nimport json\n"
+      source << "import asyncio\n" if asynchronous?
+      source << "\nfrom haveapi_client import #{package_imports}\n\n\n"
+      source << "#{'async ' if asynchronous?}def main() -> None:\n    try:\n"
+      options = ["version=#{python_literal(api_version)}"]
+      options << "auth=#{auth}" if auth
+      source << "        #{'async ' if asynchronous?}with #{client_name}(#{python_literal(api_base)}, #{options.join(', ')}) as api:\n"
+      source << indent(body, 12)
+      source << indent(<<~PY, 4)
+        except ActionError as error:
+            print(error.message, error.errors)
+        except HaveAPIError as error:
+            print(error.message, error.status_code)
+      PY
+      source << "\n\nif __name__ == \"__main__\":\n    #{asynchronous? ? 'asyncio.run(main())' : 'main()'}\n"
+      source
+    end
+
+    def init
+      code_result { program("print(\"Discovery complete\")\n") }
+    end
+
+    def auth(method, description)
+      return limitation('This authentication provider is not advertised or supported by this client.') unless supported_auth?(method)
+
+      code_result do
+        case method.to_sym
+        when :basic
+          program("print(\"Authenticated\")\n", imports: ['BasicAuth'],
+                                                auth: 'BasicAuth(os.environ["HAVEAPI_USER"], os.environ["HAVEAPI_PASSWORD"])')
+        when :oauth2
+          source = program("print(\"Authenticated\")\n", imports: ['OAuth2Auth'],
+                                                         auth: 'OAuth2Auth(os.environ["HAVEAPI_ACCESS_TOKEN"])')
+          "# Use an existing access token; OAuth acquisition and refresh are outside this client.\n#{source}"
+        when :token
+          fields = token_login_fields(description).merge(token_request_fields(description).select do |_, parameter|
+            field(parameter, :required)
+          end)
+          if fields.empty?
+            program("print(\"Authenticated\")\n", imports: ['TokenAuth'], auth: 'TokenAuth(os.environ["HAVEAPI_TOKEN"])')
+          else
+            challenge = asynchronous? ? 'AsyncAuthenticationChallenge' : 'AuthenticationChallenge'
+            input = fields.map do |name, _|
+              "#{python_literal(name.to_s)}: json.loads(os.environ[#{python_literal("HAVEAPI_AUTH_#{name}")}])"
+            end.join(', ')
+            body = <<~PY
+              if "HAVEAPI_TOKEN" in os.environ:
+                  #{await_prefix}api.set_auth(TokenAuth(os.environ["HAVEAPI_TOKEN"]))
+              else:
+                  # HAVEAPI_AUTH_* and HAVEAPI_CHALLENGE_* contain JSON values.
+                  step = #{await_prefix}api.begin_token_login({#{input}})
+                  while isinstance(step, #{challenge}):
+                      values = {
+                          name: json.loads(os.environ["HAVEAPI_CHALLENGE_" + name])
+                          for name in step.input if name != "token"
+                      }
+                      step = #{await_prefix}step.submit(values)
+              print("Authenticated")
+            PY
+            program(body, imports: ['TokenAuth', challenge])
+          end
+        end
+      end
+    end
+
+    def example(sample)
+      code_result do
+        path, request = structured_sample(sample)
+        method = field(current_action, :method).to_s.upcase
+        unless %w[GET POST PUT DELETE].include?(method)
+          raise Unsupported, 'This Python client supports GET, POST, PUT and DELETE actions only.'
+        end
+        unless request.nil? || request.is_a?(Hash) || request.is_a?(Array)
+          raise Unsupported, 'This Python client requires object or list input.'
+        end
+        if request.is_a?(Array) && field(field(current_action, :input), :namespace).to_s.empty?
+          raise Unsupported, 'This Python client requires a namespace for list input.'
+        end
+
+        check_get_sample(request) if method == 'GET'
+
+        resource = current_resource_path.each_with_index.map do |name, index|
+          "#{'api' if index == 0}.resources[#{python_literal(name)}]"
+        end.join
+        arguments = []
+        arguments << "path_params=#{python_literal(path)}" unless path.empty?
+        arguments << "params=#{python_literal(request)}" unless request.nil?
+        body = "response = #{await_prefix}#{resource}.actions[#{python_literal(current_action_name)}].call(#{arguments.join(', ')})\n"
+        body << "print(response.data)\nprint(response.meta)\n"
+        if field(current_action, :blocking)
+          body << <<~PY
+            # A request timeout does not cancel a server operation.
+            if response.operation is not None:
+                completed = #{await_prefix}response.operation.wait(timeout=300, interval=1)
+                print(completed)
+          PY
+        end
+        if field(current_action, :auth)
+          method = %i[token basic oauth2].find { |name| supported_auth?(name) }
+          raise Unsupported, 'This action requires an authentication provider unsupported by this client.' unless method
+
+          provider, auth = {
+            token: ['TokenAuth', 'TokenAuth(os.environ["HAVEAPI_TOKEN"])'],
+            basic: ['BasicAuth', 'BasicAuth(os.environ["HAVEAPI_USER"], os.environ["HAVEAPI_PASSWORD"])'],
+            oauth2: ['OAuth2Auth', 'OAuth2Auth(os.environ["HAVEAPI_ACCESS_TOKEN"])']
+          }.fetch(method)
+          program(body, imports: [provider], auth:)
+        else
+          program(body)
+        end
+      end
+    end
+
+    def check_get_sample(request)
+      input = field(current_action, :input)
+      namespace = field(input, :namespace)
+      parameters = field(input, :parameters, {}).to_h { |name, parameter| [name.to_s, parameter] }
+      safe_component = ->(value) { !value.to_s.empty? && !value.to_s.match?(/[\[\]]/) }
+      safe_namespace = !namespace || safe_component.call(namespace)
+      # Deliberately support a flat subset, leaving the full Rack encoder to the client.
+      safe_request = request.nil? || (request.is_a?(Hash) && request.all? do |name, value|
+        parameter = field(parameters, name)
+        custom = field(parameter, :type) == 'Custom'
+        scalar = !value.is_a?(Hash) && !value.is_a?(Array)
+        custom_value = value.is_a?(String) || (value.nil? && field(parameter, :nullable))
+        safe_component.call(name) && scalar && (!custom || custom_value)
+      end)
+      return if safe_namespace && safe_request
+
+      raise Unsupported, 'Python GET examples support flat scalar input with bracket-free names; Custom values must be strings or nullable nulls.'
+    end
+  end
+end

data/lib/haveapi/client_examples/rust_client.rb

@@ -0,0 +1,59 @@
+require 'haveapi/client_example'
+
+module HaveAPI::ClientExamples
+  class RustClient < HaveAPI::ClientExample
+    class << self
+      def available?(context)
+        context&.profile&.language == :rust
+      end
+    end
+
+    def init
+      render_rust(:init)
+    end
+
+    def auth(method, desc)
+      render_rust(:auth, auth_method: method, auth_description: desc)
+    end
+
+    def example(sample)
+      render_rust(:example, rendering_context: context&.with(sample:))
+    end
+
+    private
+
+    def render_rust(kind, rendering_context: context, **)
+      unless self.class.available?(rendering_context)
+        return { status: :limitation, reason: 'A Rust SDK documentation profile is required.' }.freeze
+      end
+
+      rendering_context.profile.adapter.render(kind:, context: rendering_context, mode: rust_mode, **)
+    end
+  end
+
+  class RustAsyncClient < RustClient
+    id 'rust-async'
+    label 'Rust (async)'
+    code :rust
+    order 17
+
+    private
+
+    def rust_mode
+      :async
+    end
+  end
+
+  class RustBlockingClient < RustClient
+    id 'rust-blocking'
+    label 'Rust (blocking)'
+    code :rust
+    order 18
+
+    private
+
+    def rust_mode
+      :blocking
+    end
+  end
+end

data/lib/haveapi/client_examples/ts_async_client.rb

@@ -0,0 +1,14 @@
+require 'haveapi/client_examples/ts_client'
+
+module HaveAPI::ClientExamples
+  class TsAsyncClient < TsClient
+    label 'TypeScript (async)'
+    id 'typescript-async'
+    code :typescript
+    order 13
+
+    def asynchronous?
+      true
+    end
+  end
+end

data/lib/haveapi/client_examples/ts_client.rb

@@ -0,0 +1,14 @@
+require 'haveapi/client_examples/js_client'
+
+module HaveAPI::ClientExamples
+  class TsClient < JsClient
+    label 'TypeScript (callback)'
+    id 'typescript-callback'
+    code :typescript
+    order 12
+
+    def typescript?
+      true
+    end
+  end
+end