haveapi 0.31.1 → 0.32.0

data/lib/haveapi/client_examples/python_client.rb

@@ -5,10 +5,17 @@ module HaveAPI::ClientExamples
     include DynamicHelpers
 
     label 'Python (sync)'
+    language 'python'
+    language_label 'Python'
+    variant 'Sync'
     id 'python-sync'
     code :python
     order 14
 
+    def self.detail_levels_for(_kind, context:, result:, auth_method: nil, auth_description: nil)
+      result[:status] == :limitation ? SIMPLE_DETAIL_LEVELS : DEFAULT_DETAIL_LEVELS
+    end
+
     def asynchronous?
       false
     end
@@ -35,68 +42,66 @@ module HaveAPI::ClientExamples
       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"
+    def program(body, imports: [], stdlib: [], auth: nil)
+      package_imports = ([client_name] + (thorough? ? %w[ActionError HaveAPIError] : []) + imports).uniq.join(', ')
+      source = (stdlib + (asynchronous? ? ['asyncio'] : [])).uniq.map { |name| "import #{name}\n" }.join
+      source << "\n" unless source.empty?
+      source << "from haveapi_client import #{package_imports}#{asynchronous? ? "\n\n\n" : "\n\n"}"
+      source << "async def main() -> None:\n" if asynchronous?
+      level = asynchronous? ? 4 : 0
+      if thorough?
+        source << indent("try:\n", level)
+        level += 4
+      end
       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 << indent("#{'async ' if asynchronous?}with #{client_name}(#{python_literal(api_base)}, #{options.join(', ')}) as api:\n", level)
+      source << indent(body, level + 4)
+      if thorough?
+        source << indent(<<~PY, level - 4)
+          except ActionError as error:
+              print(error.message, error.errors)
+          except HaveAPIError as error:
+              print(error.message, error.status_code)
+        PY
+      end
+      source << "\n\nasyncio.run(main())\n" if asynchronous?
       source
     end
 
     def init
-      code_result { program("print(\"Discovery complete\")\n") }
+      code_result { program(thorough? ? "print(\"Discovery complete\")\n" : "# Call API actions inside this block.\npass\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
+        body = thorough? ? "print(\"Authenticated\")\n" : "# Call API actions inside this block.\npass\n"
         case method.to_sym
         when :basic
-          program("print(\"Authenticated\")\n", imports: ['BasicAuth'],
-                                                auth: 'BasicAuth(os.environ["HAVEAPI_USER"], os.environ["HAVEAPI_PASSWORD"])')
+          program(body, imports: ['BasicAuth'], auth: 'BasicAuth("user", "secret")')
         when :oauth2
-          source = program("print(\"Authenticated\")\n", imports: ['OAuth2Auth'],
-                                                         auth: 'OAuth2Auth(os.environ["HAVEAPI_ACCESS_TOKEN"])')
+          source = program(body, imports: ['OAuth2Auth'], auth: 'OAuth2Auth("example-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"])')
+          if token_login_fields(description).empty?
+            program(body, imports: ['TokenAuth'], auth: 'TokenAuth("example-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")
+              continuations = #{python_literal(auth_token_continuations(description))}
+              step = #{await_prefix}api.begin_token_login(#{python_literal(auth_token_credentials(description))})
+              while isinstance(step, #{challenge}):
+                  if step.next_action not in continuations:
+                      raise ValueError("Unknown authentication continuation")
+                  values = continuations[step.next_action]
+                  if any(name != "token" and name not in values for name in step.input):
+                      raise ValueError("Unknown authentication input")
+                  step = #{await_prefix}step.submit(values)
             PY
-            program(body, imports: ['TokenAuth', challenge])
+            body << "print(\"Authenticated\")\n" if thorough?
+            program(body, imports: [challenge])
           end
         end
       end
@@ -125,7 +130,8 @@ module HaveAPI::ClientExamples
         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"
+        body << "print(response.data)\n"
+        body << "print(response.meta)\n" if thorough?
         if field(current_action, :blocking)
           body << <<~PY
             # A request timeout does not cancel a server operation.
@@ -139,17 +145,25 @@ module HaveAPI::ClientExamples
           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"])']
+            token: ['TokenAuth', 'TokenAuth("example-token")'],
+            basic: ['BasicAuth', 'BasicAuth("user", "secret")'],
+            oauth2: ['OAuth2Auth', 'OAuth2Auth("example-access-token")']
           }.fetch(method)
-          program(body, imports: [provider], auth:)
+          if thorough?
+            program(body, imports: [provider], auth:)
+          else
+            action_fragment(body)
+          end
         else
-          program(body)
+          thorough? ? program(body) : action_fragment(body)
         end
       end
     end
 
+    def action_fragment(body)
+      asynchronous? ? "# Run inside an async function after initializing api.\n#{body}" : body
+    end
+
     def check_get_sample(request)
       input = field(current_action, :input)
       namespace = field(input, :namespace)

data/lib/haveapi/client_examples/ruby_cli.rb

@@ -1,3 +1,4 @@
+require 'shellwords'
 module HaveAPI
   module CLI; end
 end
@@ -8,11 +9,14 @@ require 'haveapi/client_example'
 module HaveAPI::ClientExamples
   class RubyCli < HaveAPI::ClientExample
     label 'CLI'
+    language 'cli'
+    language_label 'CLI'
+    detail_levels :simple
     code :bash
     order 30
 
     def init
-      "$ haveapi-cli -u #{base_url} --version #{version}"
+      "$ haveapi-cli -u #{Shellwords.escape(base_url.to_s)} --version #{Shellwords.escape(version.to_s)}"
     end
 
     def auth(method, desc)
@@ -24,7 +28,7 @@ module HaveAPI::ClientExamples
 
           # If username or password isn't provided, the user is asked on stdin
           #{init} --auth basic --user user
-          Password: secret
+          # Password: secret
         END
 
       when :token
@@ -33,8 +37,8 @@ module HaveAPI::ClientExamples
           # Note that the client always has to call some action. APIs should provide
           # an action to get information about the current user, so that's what we're
           # calling now.
-          #{init} --auth token #{auth_token_credentials(desc, password: false).map { |k, v| "--#{k} #{v}" }.join(' ')} --save user current
-          Password: secret
+          #{init} --auth token #{auth_token_credentials(desc, password: false).map { |k, v| "#{Shellwords.escape("--#{k}")} #{Shellwords.escape(v.to_s)}" }.join(' ')} --save user current
+          # Password: secret
 
           # Now the token is read from disk and the user does not have to provide username
           # nor password and be authenticated
@@ -44,13 +48,15 @@ module HaveAPI::ClientExamples
       when :oauth2
         '# OAuth2 is not supported by HaveAPI Ruby CLI.'
       end
+    rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
+      { status: :limitation, reason: e.message }.freeze
     end
 
     def example(sample)
       cmd = [init]
-      cmd << resource_path.join('.')
-      cmd << action_name
-      cmd.concat(sample[:path_params]) if sample[:path_params]
+      cmd << Shellwords.escape(resource_path.join('.'))
+      cmd << Shellwords.escape(action_name.to_s)
+      cmd.concat(sample[:path_params].map { |value| Shellwords.escape(value.to_s) }) if sample[:path_params]
 
       if sample[:request] && !sample[:request].empty?
         cmd << "-- \\\n"
@@ -65,16 +71,16 @@ module HaveAPI::ClientExamples
 
       return response(sample, res) if sample[:status]
 
-      res << "\nAction failed: #{sample[:message]}\n"
+      display = "Action failed: #{sample[:message]}\n"
 
       if sample[:errors] && sample[:errors].any?
-        res << "Errors:\n"
+        display << "Errors:\n"
         sample[:errors].each do |param, e|
-          res << "\t#{param}: #{e.join('; ')}\n"
+          display << "\t#{param}: #{e.join('; ')}\n"
         end
       end
 
-      res
+      res << "\n" << comment_response(display)
     end
 
     def response(sample, res)
@@ -101,21 +107,24 @@ module HaveAPI::ClientExamples
         cols << col
       end
 
-      res << "\n" << HaveAPI::CLI::OutputFormatter.to_s(
-        sample[:response],
-        cols
-      )
-      res
+      display = HaveAPI::CLI::OutputFormatter.to_s(sample[:response], cols)
+      res << "\n" << comment_response(display)
     end
 
     def input_param(name, value)
       option = name.to_s.gsub('_', '-')
 
       if action[:input][:parameters][name][:type] == 'Boolean'
-        return value ? "--#{option}" : "--no-#{name}"
+        return Shellwords.escape(value ? "--#{option}" : "--no-#{name}")
       end
 
-      "--#{option} '#{value}'"
+      "#{Shellwords.escape("--#{option}")} #{Shellwords.escape(value.to_s)}"
+    end
+
+    private
+
+    def comment_response(fragment)
+      fragment.gsub(/\r\n?/, "\n").lines.map { |line| "# #{line.delete_suffix("\n")}\n" }.join
     end
   end
 end

data/lib/haveapi/client_examples/ruby_client.rb

@@ -4,45 +4,91 @@ require 'haveapi/client_example'
 module HaveAPI::ClientExamples
   class RubyClient < HaveAPI::ClientExample
     label 'Ruby'
+    language 'ruby'
+    language_label 'Ruby'
     code :ruby
     order 0
 
-    def init
-      <<~END
-        require 'haveapi-client'
+    def self.detail_levels_for(kind, context:, result:, auth_method: nil, auth_description: nil)
+      result[:status] == :limitation || (kind == :auth && auth_method == :oauth2) ? SIMPLE_DETAIL_LEVELS : DEFAULT_DETAIL_LEVELS
+    end
 
-        client = HaveAPI::Client.new("#{base_url}", version: "#{version}")
-      END
+    def initialization
+      "require 'haveapi/client'\n\napi = HaveAPI::Client.new(#{base_url.dump}, version: #{version.to_s.dump})\n"
     end
 
-    def auth(method, desc)
-      case method
-      when :basic
-        <<~END
-          #{init}
+    def with_error_handling(body)
+      <<~RUBY
+        begin
+        #{body.lines.map { |line| line == "\n" ? line : "  #{line}" }.join.chomp}
+        rescue HaveAPI::Client::ValidationError => error
+          warn error.message
+          warn error.errors.inspect
+        rescue HaveAPI::Client::ActionFailed => error
+          warn error.message
+          warn error.response.errors.inspect if error.response.is_a?(HaveAPI::Client::Response)
+        rescue HaveAPI::Client::Authentication::AuthenticationFailed, HaveAPI::Client::ProtocolError,
+               RestClient::Exception, JSON::ParserError => error
+          warn error.message
+        end
+      RUBY
+    end
 
-          client.authenticate(:basic, user: "user", password: "secret")
-        END
+    def init
+      thorough? ? with_error_handling("#{initialization}api.setup\n") : initialization
+    end
 
-      when :token
-        <<~END
-          #{init}
+    def auth_login_literal(name, parameter, value)
+      return value unless value == false || value.nil?
 
-          # Get token using username and password
-          client.authenticate(:token, #{auth_token_credentials(desc).map { |k, v| "#{k}: \"#{v}\"" }.join(', ')})
+      # Token#request_token copies only truthy login options.
+      auth_literal(name, parameter, excluding: [false, nil])
+    end
 
-          puts "Token = \#{client.auth.token}"
+    def auth(method, desc)
+      body = case method
+             when :basic
+               "api.authenticate(:basic, user: 'user', password: 'secret')"
+             when :token
+               input = auth_token_credentials(desc).transform_keys(&:to_sym)
+               continuations = auth_token_continuations(desc)
+               code = "api.authenticate(:token, **#{input.inspect})"
+               unless continuations.empty?
+                 code << <<~RUBY
+                    do |action, parameters|
+                     continuations = #{continuations.inspect}
+                     input = continuations.fetch(action.to_s) { raise ArgumentError, 'Unknown authentication continuation' }
+                     unless (parameters.keys.map(&:to_s) - input.keys - ['token']).empty?
+                       raise ArgumentError, 'Unknown authentication input'
+                     end
+                     input.transform_keys(&:to_sym)
+                   end
+                 RUBY
+               end
+               %(#{code.chomp}\n\n# Reuse an existing token\napi.authenticate(:token, token: 'example-token'))
+             when :oauth2
+               return '# OAuth2 is not supported by HaveAPI Ruby client.'
+             end
+      return unless body
+
+      source = [initialization.chomp, (thorough? ? 'api.setup' : nil), body].compact.join("\n\n")
+      thorough? ? with_error_handling(source) : source
+    rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
+      { status: :limitation, reason: e.message }.freeze
+    end
 
-          # Next time, the client can authenticate using the token directly
-          client.authenticate(:token, token: saved_token)
-        END
+    def action_authentication
+      return '' unless action[:auth] && context
 
-      when :oauth2
-        '# OAuth2 is not supported by HaveAPI Ruby client.'
-      end
+      providers = auth_field(context.description, :authentication, {}).keys.map(&:to_s)
+      return "api.authenticate(:token, token: 'example-token')\n" if providers.include?('token')
+      return "api.authenticate(:basic, user: 'user', password: 'secret')\n" if providers.include?('basic')
+
+      raise HaveAPI::ClientExample::UnsupportedAuthentication, 'This action requires authentication unsupported by this client.'
     end
 
     def example(sample)
+      credentials = action_authentication
       args = []
 
       args.concat(sample[:path_params]) if sample[:path_params]
@@ -51,15 +97,18 @@ module HaveAPI::ClientExamples
         args << PP.pp(sample[:request], '').strip
       end
 
-      out = "#{init}\n"
-      out << "reply = client.#{resource_path.join('.')}.#{action_name}"
+      out = +''
+      out << "reply = api.#{resource_path.join('.')}.#{action_name}"
       out << "(#{args.join(', ')})" unless args.empty?
 
-      return out << response(sample) if sample[:status]
-
-      out << "\n"
-      out << '# Raises exception HaveAPI::Client::ActionFailed'
-      out
+      out << if sample[:status]
+               response(sample)
+             else
+               "\n# Raises exception HaveAPI::Client::ActionFailed\n"
+             end
+      thorough? ? with_error_handling(["#{initialization}api.setup", credentials.chomp, out].reject(&:empty?).join("\n\n")) : out
+    rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
+      { status: :limitation, reason: e.message }.freeze
     end
 
     def response(sample)

data/lib/haveapi/client_examples/rust_client.rb

@@ -6,6 +6,11 @@ module HaveAPI::ClientExamples
       def available?(context)
         context&.profile&.language == :rust
       end
+
+      def detail_levels_for(kind, context:, result:, auth_method: nil, auth_description: nil)
+        adapter_detail_levels_for(adapter: context.profile.adapter, kind:, context:, result:,
+                                  mode: rust_mode, auth_method:, auth_description:)
+      end
     end
 
     def init
@@ -22,9 +27,13 @@ module HaveAPI::ClientExamples
 
     private
 
+    def rust_mode
+      self.class.rust_mode
+    end
+
     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
+        return { status: :limitation, reason: 'A Rust API client documentation profile is required.' }.freeze
       end
 
       rendering_context.profile.adapter.render(kind:, context: rendering_context, mode: rust_mode, **)
@@ -33,26 +42,28 @@ module HaveAPI::ClientExamples
 
   class RustAsyncClient < RustClient
     id 'rust-async'
-    label 'Rust (async)'
+    label 'Rust API client (async)'
+    language 'rust'
+    language_label 'Rust'
+    variant 'Async'
     code :rust
     order 17
 
-    private
-
-    def rust_mode
+    def self.rust_mode
       :async
     end
   end
 
   class RustBlockingClient < RustClient
     id 'rust-blocking'
-    label 'Rust (blocking)'
+    label 'Rust API client (blocking)'
+    language 'rust'
+    language_label 'Rust'
+    variant 'Blocking'
     code :rust
     order 18
 
-    private
-
-    def rust_mode
+    def self.rust_mode
       :blocking
     end
   end

data/lib/haveapi/client_examples/ts_async_client.rb

@@ -3,10 +3,17 @@ require 'haveapi/client_examples/ts_client'
 module HaveAPI::ClientExamples
   class TsAsyncClient < TsClient
     label 'TypeScript (async)'
+    language 'typescript'
+    language_label 'TypeScript'
+    variant 'Async'
     id 'typescript-async'
     code :typescript
     order 13
 
+    def self.detail_levels_for(_kind, context:, result:, auth_method: nil, auth_description: nil)
+      result[:status] == :limitation ? SIMPLE_DETAIL_LEVELS : DEFAULT_DETAIL_LEVELS
+    end
+
     def asynchronous?
       true
     end

data/lib/haveapi/client_examples/ts_client.rb

@@ -3,6 +3,9 @@ require 'haveapi/client_examples/js_client'
 module HaveAPI::ClientExamples
   class TsClient < JsClient
     label 'TypeScript (callback)'
+    language 'typescript'
+    language_label 'TypeScript'
+    variant 'Callback'
     id 'typescript-callback'
     code :typescript
     order 12

data/lib/haveapi/client_examples/ts_generated_client.rb

@@ -3,7 +3,10 @@ require 'haveapi/client_example'
 module HaveAPI::ClientExamples
   class TsGeneratedClient < HaveAPI::ClientExample
     id 'typescript-generated'
-    label 'TypeScript (generated)'
+    label 'TypeScript API client'
+    language 'typescript'
+    language_label 'TypeScript'
+    variant 'API client'
     code :typescript
     order 19
 
@@ -11,6 +14,11 @@ module HaveAPI::ClientExamples
       context&.profile&.language == :typescript
     end
 
+    def self.detail_levels_for(kind, context:, result:, auth_method: nil, auth_description: nil)
+      adapter_detail_levels_for(adapter: context.profile.adapter, kind:, context:, result:,
+                                mode: :async, auth_method:, auth_description:)
+    end
+
     def init
       render_documentation(:init)
     end
@@ -27,7 +35,7 @@ module HaveAPI::ClientExamples
 
     def render_documentation(kind, rendering_context: context, **)
       unless self.class.available?(rendering_context)
-        return { status: :limitation, reason: 'A generated TypeScript SDK documentation profile is required.' }.freeze
+        return { status: :limitation, reason: 'A TypeScript API client documentation profile is required.' }.freeze
       end
 
       rendering_context.profile.adapter.render(kind:, context: rendering_context, mode: :async, **)

data/lib/haveapi/documentation_context.rb

@@ -4,12 +4,12 @@ module HaveAPI
   class ClientExample
     # A request-local snapshot: never freeze or retain the server's shared help.
     class Context
-      FIELDS = %i[version host base_url version_url description resource_path resource action_name action sample profile].freeze
+      FIELDS = %i[version host base_url version_url description resource_path resource action_name action sample profile detail].freeze
       attr_reader(*FIELDS)
 
       def initialize(version:, host:, base_url:, version_url:, description:,
                      resource_path: [], resource: nil, action_name: nil, action: nil,
-                     sample: nil, profile: nil)
+                     sample: nil, profile: nil, detail: :simple)
         @version = normalize(:version, version)
         @host = normalize(:host, host)
         @base_url = normalize(:base_url, base_url)
@@ -21,6 +21,7 @@ module HaveAPI
         @action = normalize(:action, action)
         @sample = normalize(:sample, sample)
         @profile = normalize(:profile, profile)
+        @detail = normalize(:detail, detail)
         freeze
       end
 
@@ -54,6 +55,10 @@ module HaveAPI
         when :action_name
           value.nil? ? nil : value.to_s.dup.freeze
         when :profile
+          value
+        when :detail
+          raise ArgumentError, 'detail must be :simple or :thorough' unless %i[simple thorough].include?(value)
+
           value
         else
           copy(value)