haveapi 0.31.1 → 0.32.0

data/lib/haveapi/client_examples/go_client.rb

@@ -2,7 +2,9 @@ require 'haveapi/client_example'
 
 module HaveAPI::ClientExamples
   class GoClient < HaveAPI::ClientExample
-    label 'Go'
+    label 'Go API client'
+    language 'go'
+    language_label 'Go'
     id 'go'
     code :go
     order 16
@@ -11,6 +13,11 @@ module HaveAPI::ClientExamples
       context.profile && context.profile.language == :go
     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: :sync, auth_method:, auth_description:)
+    end
+
     def init
       render_documentation(:init)
     end
@@ -27,7 +34,7 @@ module HaveAPI::ClientExamples
 
     def render_documentation(kind, sample: nil, **)
       unless context && self.class.available?(context)
-        return { status: :limitation, reason: 'A Go SDK profile is required.' }.freeze
+        return { status: :limitation, reason: 'A Go API client profile is required.' }.freeze
       end
 
       selected = kind == :example ? context.with(sample:) : context

data/lib/haveapi/client_examples/http.rb

@@ -5,6 +5,9 @@ require 'haveapi/client_example'
 module HaveAPI::ClientExamples
   class Http < HaveAPI::ClientExample
     label 'HTTP'
+    language 'http'
+    language_label 'HTTP'
+    detail_levels :simple
     code :http
     order 100
 
@@ -27,7 +30,7 @@ module HaveAPI::ClientExamples
         END
 
       when :token
-        login = auth_token_credentials(desc).merge(lifetime: 'fixed')
+        login = auth_token_credentials(desc)
 
         <<~END
           POST /_auth/token/tokens HTTP/1.1
@@ -40,22 +43,24 @@ module HaveAPI::ClientExamples
       when :oauth2
         <<~END
           # 1) Request authorization code
-          GET #{desc[:authorize_path]}?response_type=code&client_id=$client_id&state=$state&redirect_uri=$client_redirect_uri HTTP/1.1
+          GET #{desc[:authorize_path]}?response_type=code&client_id=example-client&state=example-state&redirect_uri=https%3A%2F%2Fexample.org%2Fcallback HTTP/1.1
           Host: #{host}
 
           # 2) The user logs in using this API
 
           # 3) The API then redirects the user back to the client application
-          GET $client_redirect_uri?code=$authorization_code&state=$state
+          GET /callback?code=example-code&state=example-state
           Host: client-application
 
           # 4) The client application requests access token
           POST #{desc[:token_path]}
           Content-Type: application/x-www-form-urlencoded
 
-          grant_type=authorization_code&code=$authorization_code&redirect_uri=$client_redirect_uri&client_id=$client_id&client_secret=$client_secret
+          grant_type=authorization_code&code=example-code&redirect_uri=https%3A%2F%2Fexample.org%2Fcallback&client_id=example-client&client_secret=example-client-secret
         END
       end
+    rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
+      { status: :limitation, reason: e.message }.freeze
     end
 
     def request(sample)

data/lib/haveapi/client_examples/js_async_client.rb

@@ -3,10 +3,17 @@ require 'haveapi/client_examples/js_client'
 module HaveAPI::ClientExamples
   class JsAsyncClient < JsClient
     label 'JavaScript (async)'
+    language 'javascript'
+    language_label 'JavaScript'
+    variant 'Async'
     id 'javascript-async'
     code :javascript
     order 11
 
+    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/js_client.rb

@@ -5,10 +5,17 @@ module HaveAPI::ClientExamples
     include DynamicHelpers
 
     label 'JavaScript (callback)'
+    language 'javascript'
+    language_label 'JavaScript'
+    variant 'Callback'
     id 'javascript-callback'
     code :javascript
     order 10
 
+    def self.detail_levels_for(kind, context:, result:, auth_method: nil, auth_description: nil)
+      kind == :example && result[:status] != :limitation ? DEFAULT_DETAIL_LEVELS : SIMPLE_DETAIL_LEVELS
+    end
+
     def asynchronous?
       false
     end
@@ -37,21 +44,24 @@ module HaveAPI::ClientExamples
       asynchronous? ? 'AsyncClient' : 'CallbackClient'
     end
 
-    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
-
     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
+      imports = "import { #{client_name}#{', AsyncError' if asynchronous? && thorough?} } from \"haveapi-client\";\n"
       declaration = "const api = new #{client_name}(#{js_literal(api_base)}, {version: #{js_literal(api_version)}});\n"
+      unless thorough?
+        return "#{imports}\n#{declaration}#{authentication || "await api.setup();\n"}#{body}" if asynchronous?
+
+        return <<~JS
+          #{imports}
+          #{declaration}
+          #{authentication || 'api.setup('}(api, ready) => {
+            if (!ready) {
+              console.error("Discovery or authentication failed");
+              return;
+            }
+          #{indent(body)}});
+        JS
+      end
+
       if asynchronous?
         <<~JS
           #{imports}
@@ -71,7 +81,7 @@ module HaveAPI::ClientExamples
         <<~JS
           #{imports}
           #{declaration}
-          #{authentication || 'api.setup('}(client, ready) => {
+          #{authentication || 'api.setup('}(api, ready) => {
             if (!ready) {
               console.error("Discovery or authentication failed");
               return;
@@ -86,7 +96,7 @@ module HaveAPI::ClientExamples
     end
 
     def init
-      code_result { program("console.log(\"Discovery complete\");\n") }
+      code_result { program(thorough? ? "console.log(\"Discovery complete\");\n" : '') }
     end
 
     def action_authentication
@@ -96,9 +106,9 @@ module HaveAPI::ClientExamples
       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")}}'
+        token: '{token: "example-token"}',
+        basic: '{user: "user", password: "secret"}',
+        oauth2: '{access_token: {access_token: "example-access-token"}}'
       }.fetch(method)
       if asynchronous?
         "await api.authenticate(#{js_literal(method.to_s)}, #{options});\n"
@@ -113,42 +123,41 @@ module HaveAPI::ClientExamples
       code_result do
         options = case method.to_sym
                   when :basic
-                    '{user: credential("HAVEAPI_USER"), password: credential("HAVEAPI_PASSWORD")}'
+                    '{user: "user", password: "secret"}'
                   when :token
                     if token_login_fields(description).empty?
-                      '{token: credential("HAVEAPI_TOKEN")}'
+                      '{token: "example-token"}'
                     else
-                      "env.HAVEAPI_TOKEN !== undefined ? {token: credential(\"HAVEAPI_TOKEN\")} : #{token_login_options(description)}"
+                      token_login_options(description)
                     end
                   when :oauth2
-                    '{access_token: {access_token: credential("HAVEAPI_ACCESS_TOKEN")}}'
+                    '{access_token: {access_token: "example-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:)
+        source = program(thorough? ? "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
 
     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
+      fields = auth_token_credentials(description).map { |name, value| "[#{js_literal(name)}]: #{js_literal(value)}" }
+      continuations = auth_token_continuations(description)
       challenge = asynchronous? ? 'onChallenge' : 'callback'
-      annotation = typescript? ? ': Record<string, unknown>' : ''
+      annotation = typescript? ? ': Record<string, Record<string, unknown>>' : ''
       fields << <<~JS.strip
         #{challenge}: (action, parameters) => {
-          const input#{annotation} = Object.create(null);
+          const continuations#{annotation} = #{js_literal(continuations)};
+          if (!Object.prototype.hasOwnProperty.call(continuations, action)) throw new Error("Unknown authentication continuation");
+          const input = continuations[action];
           for (const name of Object.keys(parameters)) {
-            if (name !== "token") input[name] = JSON.parse(credential("HAVEAPI_CHALLENGE_" + name));
+            if (name !== "token" && !Object.prototype.hasOwnProperty.call(input, name)) throw new Error("Unknown authentication input");
           }
           return input;
         }
@@ -179,13 +188,14 @@ module HaveAPI::ClientExamples
           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"
+          body << "console.log(result.value);\n"
+          body << "console.log(result.response.meta);\n" if thorough?
           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 resource = CallbackClient.findResource(api, #{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
@@ -195,13 +205,14 @@ module HaveAPI::ClientExamples
                 return;
               }
               console.log(reply.response());
-              console.log(reply.meta());
-            }
           JS
+          options << "  console.log(reply.meta());\n" if thorough?
+          options << "}\n"
           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)
+        authentication = action_authentication
+        thorough? ? program(body, authentication:) : body
       end
     end
   end

data/lib/haveapi/client_examples/php_client.rb

@@ -3,85 +3,159 @@ require 'haveapi/client_example'
 module HaveAPI::ClientExamples
   class PhpClient < HaveAPI::ClientExample
     label 'PHP'
+    language 'php'
+    language_label 'PHP'
     code :php
     order 20
 
+    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 initialization
+      "$api = new \\HaveAPI\\Client(#{value(base_url)}, #{value(version.to_s)});\n"
+    end
+
+    def with_error_handling(body)
+      <<~PHP
+        try {
+        #{body.lines.map { |line| line == "\n" ? line : "    #{line}" }.join.chomp}
+        } catch (\\HaveAPI\\Client\\Exception\\ValidationError $error) {
+            echo $error->getMessage() . "\\n";
+            print_r($error->getErrors());
+        } catch (\\HaveAPI\\Client\\Exception\\ActionFailed $error) {
+            echo $error->getMessage() . "\\n";
+            print_r($error->getErrors());
+        } catch (\\HaveAPI\\Client\\Exception\\Base $error) {
+            echo $error->getMessage() . "\\n";
+        } catch (\\Exception $error) {
+            // Dependency failures still propagate to the application.
+            echo $error->getMessage() . "\\n";
+            throw $error;
+        }
+      PHP
+    end
+
     def init
-      <<~END
-        $api = new \\HaveAPI\\Client("#{base_url}", "#{version}");
-      END
+      thorough? ? with_error_handling("#{initialization}$api->setup();\n") : initialization
+    end
+
+    def auth_login_literal(name, parameter, value)
+      return value unless value.nil?
+
+      # Token::requestToken uses isset: false survives, explicit null does not.
+      auth_literal(name, parameter, excluding: [nil])
     end
 
     def auth(method, desc)
-      case method
-      when :basic
-        <<~END
-          #{init}
-
-          $api->authenticate("basic", ["user" => "user", "password" => "secret"]);
-        END
-
-      when :token
-        <<~END
-          #{init}
-
-          // Get token using username and password
-          $api->authenticate("token", [#{auth_token_credentials(desc).map { |k, v| "\"#{k}\" => \"#{v}\"" }.join(', ')}]);
-
-          echo "Token = ".$api->getAuthenticationProvider()->getToken();
-
-          // Next time, the client can authenticate using the token directly
-          $api->authenticate("token", ["token" => $savedToken]);
-        END
-
-      when :oauth2
-        <<~END
-          // OAuth2 requires session
-          session_start();
-
-          // Client instance
-          #{init}
-          // Check if we already have an access token
-          if (isset($_SESSION["access_token"])) {
-            // We're already authenticated, reuse the existing access token
-            $api->authenticate("oauth2", ["access_token" => $_SESSION["access_token"]]);
-
-          } else {
-            // Follow the OAuth2 authorization process to get an access token using
-            // authorization code
-            $api->authenticate("oauth2", [
-              // Client id and secret are given by the API server
-              "client_id" => "your client id",
-              "client_secret" => "your client secret",
-
-              // This example code should run on the URL below
-              "redirect_uri" => "https://your-client.tld/oauth2-callback",
-
-              // Scopes are specific to the API implementation
-              "scope" => "all",
-            ]);
-
-            $provider = $api->getAuthenticationProvider();
-
-            // We don't have authorization code yet, request one
-            if (!isset($_GET['code'])) {
-              // Redirect the user to the authorization endpoint
-              $provider->requestAuthorizationCode();
-              exit;
-
-            } else {
-              // Request access token using the token endpoint
-              $provider->requestAccessToken();
-
-              // Store the access token in the session
-              $_SESSION['access_token'] = $provider->jsonSerialize();
-            }
+      source = case method
+               when :basic
+                 <<~END
+                   #{initialization.chomp}
+
+                   $api->authenticate('basic', ['user' => 'user', 'password' => 'secret']);
+                 END
+
+               when :token
+                 <<~END
+                   #{initialization.chomp}
+
+                   // Get token using username and password
+                   $api->authenticate('token', #{token_options(desc)});
+
+                   // Next time, the client can authenticate using the token directly
+                   $api->authenticate('token', ['token' => 'example-token']);
+                 END
+
+               when :oauth2
+                 <<~END
+                   // OAuth2 requires session
+                   session_start();
+
+                   // Client instance
+                   #{initialization}
+                   // Check if we already have an access token
+                   if (isset($_SESSION['access_token'])) {
+                       // We're already authenticated, reuse the existing access token
+                       $api->authenticate('oauth2', ['access_token' => $_SESSION['access_token']]);
+                   } else {
+                       // Follow the OAuth2 authorization process to get an access token using
+                       // authorization code
+                       $api->authenticate('oauth2', [
+                           // Client id and secret are given by the API server
+                           'client_id' => 'example-client',
+                           'client_secret' => 'example-client-secret',
+
+                           // This example code should run on the URL below
+                           'redirect_uri' => 'https://your-client.tld/oauth2-callback',
+
+                           // Scopes are specific to the API implementation
+                           'scope' => 'all',
+                       ]);
+
+                       $provider = $api->getAuthenticationProvider();
+
+                       // We don't have authorization code yet, request one
+                       if (!isset($_GET['code'])) {
+                           // Redirect the user to the authorization endpoint
+                           $provider->requestAuthorizationCode();
+                           exit;
+                       } else {
+                           // Request access token using the token endpoint
+                           $provider->requestAccessToken();
+
+                           // Store the access token in the session
+                           $_SESSION['access_token'] = $provider->jsonSerialize();
+                       }
+                   }
+                 END
+               end
+      return unless source
+
+      source = source.sub(initialization, "#{initialization}$api->setup();\n") if thorough?
+      thorough? ? with_error_handling(source) : source
+    rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
+      { status: :limitation, reason: e.message }.freeze
+    end
+
+    def token_options(description)
+      fields = auth_token_credentials(description).map { |name, item| "#{value(name)} => #{value(item)}" }
+      continuations = auth_token_continuations(description)
+      unless continuations.empty?
+        fields << <<~PHP.strip
+          'callback' => function ($action, $token, $parameters) {
+              $continuations = #{value(continuations)};
+              if (!array_key_exists($action, $continuations)) {
+                  throw new \\InvalidArgumentException('Unknown authentication continuation');
+              }
+              $input = $continuations[$action];
+              foreach (array_keys((array) $parameters) as $name) {
+                  if ($name !== 'token' && !array_key_exists($name, $input)) {
+                      throw new \\InvalidArgumentException('Unknown authentication input');
+                  }
+              }
+              return $input;
           }
-        END
+        PHP
       end
+      return '[]' if fields.empty?
+
+      "[\n#{fields.map { |field| field.lines.map { |line| "    #{line}" }.join.chomp }.join(",\n")}\n]"
+    end
+
+    def action_authentication
+      return '' unless action[:auth] && context
+
+      providers = auth_field(context.description, :authentication, {}).keys.map(&:to_s)
+      return "$api->authenticate('token', ['token' => 'example-token']);" if providers.include?('token')
+      return "$api->authenticate('basic', ['user' => 'user', 'password' => 'secret']);" if providers.include?('basic')
+      return "$api->authenticate('oauth2', ['access_token' => ['access_token' => 'example-access-token']]);" if providers.include?('oauth2')
+
+      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]
@@ -90,14 +164,18 @@ module HaveAPI::ClientExamples
         args << format_parameters(:input, sample[:request])
       end
 
-      out = "#{init}\n"
+      out = +''
       out << "$reply = $api->#{resource_path.join('->')}->#{action_name}"
       out << "(#{args.join(', ')});\n"
 
-      return out << response(sample) if sample[:status]
-
-      out << '// Throws exception \\HaveAPI\\Client\\Exception\\ActionFailed'
-      out
+      out << if sample[:status]
+               response(sample)
+             else
+               '// Throws exception \\HaveAPI\\Client\\Exception\\ActionFailed'
+             end
+      thorough? ? with_error_handling(["#{initialization}$api->setup();", credentials, out.chomp].reject(&:empty?).join("\n\n")) : out
+    rescue HaveAPI::ClientExample::UnsupportedAuthentication => e
+      { status: :limitation, reason: e.message }.freeze
     end
 
     def response(sample)
@@ -148,7 +226,7 @@ module HaveAPI::ClientExamples
 
     def format_parameters(dir, params, prefix = '')
       ret = params.map do |k, v|
-        "#{prefix}  #{value(k.to_s)} => #{value(v)}"
+        "#{prefix}    #{value(k.to_s)} => #{value(v)}"
       end
 
       "#{prefix}[\n#{ret.join(",\n")}\n#{prefix}]"
@@ -165,8 +243,16 @@ module HaveAPI::ClientExamples
       when ::Hash
         "[#{v.map { |key, item| "#{value(key.to_s)} => #{value(item)}" }.join(', ')}]"
       else
-        escaped = v.to_s.gsub(/[\\']/) { |char| "\\#{char}" }
-        "'#{escaped}'"
+        string = v.to_s
+        if string.match?(/[\x00-\x1f\x7f]/)
+          escaped = string.gsub(/[\\"$\x00-\x1f\x7f]/) do |char|
+            char.ord < 32 || char.ord == 127 ? format('\\x%02x', char.ord) : "\\#{char}"
+          end
+          "\"#{escaped}\""
+        else
+          escaped = string.gsub(/[\\']/) { |char| "\\#{char}" }
+          "'#{escaped}'"
+        end
       end
     end
   end

data/lib/haveapi/client_examples/python_async_client.rb

@@ -3,6 +3,9 @@ require 'haveapi/client_examples/python_client'
 module HaveAPI::ClientExamples
   class PythonAsyncClient < PythonClient
     label 'Python (async)'
+    language 'python'
+    language_label 'Python'
+    variant 'Async'
     id 'python-async'
     code :python
     order 15