haveapi 0.31.1 → 0.32.0

data/spec/client_examples/shell_spec.rb

@@ -0,0 +1,268 @@
+require 'spec_helper'
+require 'fileutils'
+require 'json'
+require 'open3'
+require 'tmpdir'
+require_relative 'dynamic_fixture'
+
+RSpec.describe HaveAPI::ClientExamples do
+  include DynamicExampleFixture
+
+  let(:action) do
+    { method: 'POST', path: '/widgets/{widget_id}', auth: false,
+      input: { layout: :hash, namespace: :widget, parameters: { name: { type: 'String' } } },
+      output: { layout: :hash, namespace: :widget, parameters: {} } }
+  end
+  let(:sample) { { path_params: [7], request: { name: 'ordinary' }, response: {}, status: true } }
+
+  def renderer(type, base_url: 'https://docs.example/api/', version: '1', resource_path: ['widget'], action_name: 'update', contract: action)
+    type.new('docs.example', base_url, version, resource_path, {}, action_name, contract)
+  end
+
+  def capture_arguments(source, directory)
+    bin = File.join(directory, 'bin')
+    FileUtils.mkdir_p(bin)
+    %w[haveapi-cli curl].each do |name|
+      executable = File.join(bin, name)
+      File.write(executable, "#!/bin/sh\nprintf '%s\\0' \"$@\" >> \"$CAPTURE\"\n")
+      File.chmod(0o755, executable)
+    end
+    capture = File.join(directory, 'arguments')
+    FileUtils.rm_f(capture)
+    stdout, stderr, status = Open3.capture3(
+      { 'PATH' => "#{bin}:#{ENV.fetch('PATH')}", 'CAPTURE' => capture },
+      'sh', '-c', source.delete_prefix('$ ')
+    )
+    expect(status).to be_success, "#{stdout}\n#{stderr}"
+    File.binread(capture).force_encoding(Encoding::UTF_8).split("\0", -1)[0...-1]
+  end
+
+  [HaveAPI::ClientExamples::RubyCli, HaveAPI::ClientExamples::Curl].each do |type|
+    it "keeps the reported #{type.label} response substitution inert in the whole transcript", :aggregate_failures do
+      Dir.mktmpdir('haveapi-shell-response-') do |directory|
+        marker = File.join(directory, 'response-executed')
+        payload = "$(printf response-confirmed > #{marker})"
+        contract = action.merge(output: action[:output].merge(parameters: { name: { type: 'String' } }))
+        example = sample.merge(request: {}, response: { name: payload }, message: 'ok', errors: nil)
+        context = dynamic_context(base_url: 'https://docs.example/api/', version: '1', resource_path: ['widget'],
+                                  action_name: 'show', action: contract, sample: example)
+        source = type.render(:example, context:).fetch(:code)
+        argv = capture_arguments(source, directory)
+        expect(File.exist?(marker)).to be(false)
+        expect(source).to include(payload)
+        if type == HaveAPI::ClientExamples::RubyCli
+          expect(argv).to eq(['-u', 'https://docs.example/api/', '--version', '1', 'widget', 'show', '7'])
+        else
+          expect(argv).to eq(['--request', 'POST', '--data-binary', JSON.generate(widget: {}), 'https://docs.example/api/widgets/7'])
+          expect(JSON.parse(argv.fetch(3))).to eq('widget' => {})
+        end
+      end
+    end
+  end
+
+  it 'keeps complete success and failure transcripts inert at both direct details without changing request bytes' do
+    Dir.mktmpdir('haveapi-shell-transcripts-') do |directory|
+      marker = File.join(directory, 'response-executed')
+      hostile = "$(touch #{marker})\n`touch #{marker}`\r\n; touch #{marker}\r& echo '雪' \"$value\"\\\ntrailing\\"
+      request = "request\r\n雪'\"\\$(touch #{marker})"
+      parameters = { name: { type: 'String', label: hostile }, zero: { type: 'Integer' }, empty: { type: 'String' },
+                     enabled: { type: 'Boolean' }, nullable: { type: 'Custom' }, structured: { type: 'Custom' } }
+      contract = action.merge(output: action[:output].merge(parameters:))
+      values = { name: hostile, zero: 0, empty: '', enabled: false, nullable: nil, structured: { list: [false, 0, nil] } }
+      examples = [sample.merge(request: { name: request }, response: values, message: 'ok', errors: nil),
+                  sample.merge(request: { name: request }, response: [values, values], message: 'ok', errors: nil),
+                  sample.merge(request: { name: request }, response: {}, status: false, message: hostile, errors: { hostile => [hostile, 'retained diagnostic'] })]
+      [HaveAPI::ClientExamples::RubyCli, HaveAPI::ClientExamples::Curl].each do |type|
+        %i[simple thorough].each do |detail|
+          examples.each do |example|
+            context = dynamic_context(base_url: 'https://docs.example/api/', version: '1', resource_path: ['widget'],
+                                      action_name: 'show', action: contract, sample: example, detail:)
+            source = type.render(:example, context:).fetch(:code)
+            argv = capture_arguments(source, directory)
+            expect(File.exist?(marker)).to be(false)
+            expect(source).to end_with("\n")
+            if type == HaveAPI::ClientExamples::RubyCli
+              expect(argv).to eq(['-u', 'https://docs.example/api/', '--version', '1', 'widget', 'show', '7', '--', '--name', request])
+              display = source.split("\n# ", 2).fetch(1)
+              expect("# #{display}".lines).to all(start_with('# '))
+              expect(display).not_to include("\r")
+              expect(display).to include("$(touch #{marker})", "`touch #{marker}`", "; touch #{marker}", 'trailing\\')
+              expect(display).to include('Action failed:', 'Errors:', 'retained diagnostic') unless example[:status]
+              expect(display).to include('0', 'list') if example[:status]
+            else
+              expect(argv).to eq(['--request', 'POST', '--data-binary', JSON.generate(widget: { name: request }), 'https://docs.example/api/widgets/7'])
+              expect(JSON.parse(argv.fetch(3))).to eq('widget' => { 'name' => request })
+              response = source.split("\n\n", 2).fetch(1)
+              expect(response.lines).to all(start_with('# '))
+              decoded = response.lines.map { |line| line.delete_prefix('# ') }.join
+              envelope = { status: example[:status], message: example[:message], response: { widget: example[:response] }, errors: example[:errors] }
+              expect(JSON.parse(decoded)).to eq(JSON.parse(JSON.generate(envelope)))
+            end
+          end
+        end
+      end
+    end
+  end
+
+  it 'preserves direct curl JSON, raw HTTP and inherited shell response composition' do
+    example = sample.merge(response: { name: "line\r\n雪$(echo retained)" }, http_status: 200, message: 'ok', errors: nil)
+    curl = renderer(HaveAPI::ClientExamples::Curl)
+    expect(JSON.parse(curl.response(example))).to eq('status' => true, 'message' => 'ok',
+                                                     'response' => { 'widget' => { 'name' => example[:response][:name] } }, 'errors' => nil)
+    expect(curl.response(example)).not_to start_with('# ')
+    http = renderer(HaveAPI::ClientExamples::Http)
+    expect(http.request(example)).to start_with("POST /widgets/7 HTTP/1.1\nHost: docs.example\nContent-Type: application/json\n\n")
+    expect(http.response(example)).to start_with("HTTP/1.1 200 OK\nContent-Type: application/json;charset=utf-8\n")
+    context = dynamic_context(action:, sample: example)
+    [HaveAPI::ClientExamples::RubyCli, HaveAPI::ClientExamples::Curl].each do |type|
+      expect(Class.new(type).render(:example, context:)).to eq(type.render(:example, context:))
+    end
+  end
+
+  it 'keeps the reported CLI request-value breakout literal' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      marker = File.join(directory, 'request-value-executed')
+      payload = "'; printf request-value-confirmed > #{marker}; #'"
+      source = renderer(HaveAPI::ClientExamples::RubyCli).example(sample.merge(request: { name: payload }))
+      argv = capture_arguments(source, directory)
+      expect(File.exist?(marker)).to be(false)
+      expect(argv).to eq(['-u', 'https://docs.example/api/', '--version', '1', 'widget', 'update', '7', '--', '--name', payload])
+    end
+  end
+
+  it 'keeps the reported CLI base-URL separator literal' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      marker = File.join(directory, 'base-url-executed')
+      base_url = "https://docs.example/api; printf host-confirmed > #{marker}; #"
+      argv = capture_arguments(renderer(HaveAPI::ClientExamples::RubyCli, base_url:).init, directory)
+      expect(File.exist?(marker)).to be(false)
+      expect(argv).to eq(['-u', base_url, '--version', '1'])
+    end
+  end
+
+  it 'keeps the reported curl JSON substitution literal' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      marker = File.join(directory, 'request-value-executed')
+      payload = "$(printf request-value-confirmed > #{marker})"
+      argv = capture_arguments(renderer(HaveAPI::ClientExamples::Curl).request(sample.merge(request: { name: payload })), directory)
+      expect(File.exist?(marker)).to be(false)
+      expect(argv).to eq(['--request', 'POST', '--data-binary', JSON.generate(widget: { name: payload }), 'https://docs.example/api/widgets/7'])
+      expect(JSON.parse(argv.fetch(3))).to eq('widget' => { 'name' => payload })
+    end
+  end
+
+  it 'keeps the reported curl URL quote breakout literal' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      marker = File.join(directory, 'base-url-executed')
+      base_url = "https://docs.example/'$(printf host-confirmed > #{marker})'/api/"
+      argv = capture_arguments(renderer(HaveAPI::ClientExamples::Curl, base_url:).request(sample), directory)
+      expect(File.exist?(marker)).to be(false)
+      expect(argv).to eq(['--request', 'POST', '--data-binary', JSON.generate(widget: { name: 'ordinary' }), "#{base_url}widgets/7"])
+      expect(JSON.parse(argv.fetch(3))).to eq('widget' => { 'name' => 'ordinary' })
+    end
+  end
+
+  it 'preserves CLI argument order, Boolean flags and existing to_s values across shell metacharacters' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      marker = File.join(directory, 'unintended')
+      hostile = "space\tline\n雪'\"\\$value;`touch #{marker}`$(touch #{marker})"
+      values = { 'odd_name' => hostile, empty: '', zero: 0, nil_value: nil,
+                 list: [false, 0, nil], object: { nested: false }, enabled_flag: true, disabled_flag: false,
+                 at_file: '@example', escaped_at: '@@example' }
+      parameters = values.to_h { |key, _| [key, { type: 'String' }] }
+      parameters[:enabled_flag] = parameters[:disabled_flag] = { type: 'Boolean' }
+      contract = action.merge(input: action[:input].merge(parameters:))
+      generator = renderer(HaveAPI::ClientExamples::RubyCli, base_url: hostile, version: hostile,
+                                                             resource_path: [hostile, 'nested'], action_name: hostile, contract:)
+      request = sample.merge(path_params: [hostile, '', 0, nil], request: values)
+      argv = capture_arguments(generator.example(request), directory)
+      expect(argv).to eq(['-u', hostile, '--version', hostile, "#{hostile}.nested", hostile, hostile, '', '0', '', '--',
+                          '--odd-name', hostile, '--empty', '', '--zero', '0', '--nil-value', '',
+                          '--list', values[:list].to_s, '--object', values[:object].to_s,
+                          '--enabled-flag', '--no-disabled_flag', '--at-file', '@example', '--escaped-at', '@@example'])
+      expect(File.exist?(marker)).to be(false)
+      malicious_option = "option'; touch #{marker}; #"
+      contract[:input][:parameters][malicious_option] = { type: 'String' }
+      argv = capture_arguments(generator.example(sample.merge(request: { malicious_option => hostile })), directory)
+      expect(argv.last(3)).to eq(['--', "--#{malicious_option.tr('_', '-')}", hostile])
+      expect(File.exist?(marker)).to be(false)
+    end
+  end
+
+  it 'preserves curl methods, paths and complete JSON values without shell evaluation' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      marker = File.join(directory, 'unintended')
+      hostile = "\t\n雪'\"\\$value;`touch #{marker}`$(touch #{marker})"
+      values = { name: hostile, empty: '', enabled: false, zero: 0, nullable: nil,
+                 nested: { list: [false, 0, nil, '', hostile] } }
+      contract = action.merge(method: hostile, path: "/widgets/{widget_id}#{hostile}")
+      argv = capture_arguments(renderer(HaveAPI::ClientExamples::Curl, contract:).request(sample.merge(path_params: [hostile], request: values)), directory)
+      expect(argv).to eq(['--request', hostile, '--data-binary', JSON.generate(widget: values),
+                          "https://docs.example/api/widgets/#{hostile}#{hostile}"])
+      expect(JSON.parse(argv.fetch(3))).to eq(JSON.parse(JSON.generate(widget: values)))
+      expect(File.exist?(marker)).to be(false)
+    end
+  end
+
+  it 'keeps curl GET query construction and body semantics intact' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      values = { name: 'a &雪', enabled: false, zero: 0, nullable: nil }
+      argv = capture_arguments(renderer(HaveAPI::ClientExamples::Curl, contract: action.merge(method: 'GET')).request(sample.merge(request: values)), directory)
+      expect(argv).to eq(['--request', 'GET', '--data-binary', JSON.generate(widget: values),
+                          'https://docs.example/api/widgets/7?name=a+%26%E9%9B%AA&enabled=false&zero=0&nullable='])
+      expect(JSON.parse(argv.fetch(3))).to eq(JSON.parse(JSON.generate(widget: values)))
+    end
+  end
+
+  it 'encodes curl initialization and auth URLs, token headers and login values once' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      marker = File.join(directory, 'unintended')
+      hostile = "\n雪'\"\\$value;`touch #{marker}`$(touch #{marker})"
+      generator = renderer(HaveAPI::ClientExamples::Curl, base_url: "https://docs.example/#{hostile}/", version: hostile)
+      base = generator.base_url
+      expect(capture_arguments(generator.init, directory)).to eq(['--request', 'OPTIONS', generator.version_url])
+      basic = generator.auth(:basic, {})
+      first = basic.split("\n# Password: secret", 2).first.split('$ ', 2).last
+      last = basic.split('# Password given on the command line', 2).last.split('$ ', 2).last
+      expect(capture_arguments("$ #{first}", directory)).to eq(['--request', 'OPTIONS', '--user', 'user', base])
+      expect(capture_arguments("$ #{last}", directory)).to eq(['--request', 'OPTIONS', '--user', 'user:secret', base])
+      description = { http_header: hostile, resources: { token: { actions: { request: { input: { parameters: {
+        hostile => { type: 'String', required: true }, lifetime: { type: 'String', required: true }
+      } } } } } } }
+      token = generator.auth(:token, description)
+      acquire, reuse = token.split("\n\n# Use a previously acquired token", 2)
+      acquire = acquire.split('$ ', 2).last
+      reuse = reuse.split('$ ', 2).last
+      expect(capture_arguments("$ #{acquire}", directory)).to eq(['--request', 'POST', '--header', 'Content-Type: application/json',
+                                                                  '--data-binary', JSON.generate(token: { hostile => hostile, lifetime: 'fixed' }),
+                                                                  File.join(base, '_auth', 'token', 'tokens')])
+      expect(capture_arguments("$ #{reuse}", directory)).to eq(['--request', 'OPTIONS', '--header', "#{hostile}: example-token", base])
+      expect(File.exist?(marker)).to be(false)
+    end
+  end
+
+  it 'encodes CLI Basic and token command spans without changing prompts or token options' do
+    Dir.mktmpdir('haveapi-shell-') do |directory|
+      marker = File.join(directory, 'unintended')
+      hostile = "\n雪'\"\\$value;`touch #{marker}`$(touch #{marker})"
+      generator = renderer(HaveAPI::ClientExamples::RubyCli, base_url: hostile, version: hostile)
+      basic = generator.auth(:basic, {})
+      first, last = basic.split("\n\n# If username", 2)
+      first = first.split('$ ', 2).last
+      last = last.split('$ ', 2).last.split("\n# Password: secret", 2).first
+      prefix = ['-u', hostile, '--version', hostile]
+      expect(capture_arguments("$ #{first}", directory)).to eq(prefix + %w[--auth basic --user user --password secret])
+      expect(capture_arguments("$ #{last}", directory)).to eq(prefix + %w[--auth basic --user user])
+      description = { resources: { token: { actions: { request: { input: { parameters: {
+        hostile => { type: 'String', required: true }, lifetime: { type: 'String', required: true }, password: { type: 'String' }
+      } } } } } } }
+      token = generator.auth(:token, description)
+      first = token.split("\n# Password: secret", 2).first.split('$ ', 2).last
+      last = token.split('# nor password and be authenticated', 2).last.split('$ ', 2).last
+      expect(capture_arguments("$ #{first}", directory)).to eq(prefix + ['--auth', 'token', "--#{hostile}", hostile, '--lifetime', 'fixed', '--save', 'user', 'current'])
+      expect(capture_arguments("$ #{last}", directory)).to eq(prefix + %w[user current])
+      expect(token).to include('# Password: secret')
+      expect(File.exist?(marker)).to be(false)
+    end
+  end
+end

data/spec/client_examples/syntax_spec.rb

@@ -9,6 +9,7 @@ require 'haveapi/client_examples/http'
 require 'haveapi/client_examples/js_client'
 require 'haveapi/client_examples/php_client'
 require 'haveapi/client_examples/ruby_client'
+require 'haveapi/client'
 
 describe HaveAPI::ClientExamples do
   let(:action) do
@@ -70,6 +71,14 @@ describe HaveAPI::ClientExamples do
     end
   end
 
+  def execute_ruby(source)
+    Tempfile.create(['haveapi-handler-', '.rb']) do |file|
+      file.write(source)
+      file.flush
+      load file.path
+    end
+  end
+
   it 'generates valid JavaScript' do
     result = HaveAPI::ClientExamples::JsClient.new(*client_args).example(sample)
     source = result.is_a?(Hash) ? result.fetch(:code) : result
@@ -98,6 +107,18 @@ describe HaveAPI::ClientExamples do
     expect(status).to be_success, output
   end
 
+  it 'round-trips PHP data literals through plain and Thorough source without changing control bytes' do
+    renderer = HaveAPI::ClientExamples::PhpClient.new(*client_args)
+    values = ['', '$user', "quote'\"\\", "line\n    indented\r\n\t$value\\\x00\x1f\x7f ž", false, nil, 0]
+    body = "echo json_encode(#{renderer.value(values)});"
+    [body, renderer.with_error_handling(body)].each do |source|
+      output, status = Open3.capture2e('php', stdin_data: "<?php\n#{source}")
+      expect(status).to be_success, output
+      expect(JSON.parse(output)).to eq(values)
+    end
+    expect(renderer.value('public literal')).to eq("'public literal'")
+  end
+
   it 'generates shell-parseable curl requests' do
     source = HaveAPI::ClientExamples::Curl.new(*client_args).request(sample)
     status, output = syntax_check(%w[bash -n], source, '.sh')
@@ -131,4 +152,175 @@ describe HaveAPI::ClientExamples do
     expect(content_length).to eq(response_body.bytesize)
     expect(JSON.parse(response_body)).to include('status' => true)
   end
+
+  it 'runs the Ruby handlers with actual client exception classes and propagates unknown errors' do
+    context = HaveAPI::ClientExample::Context.new(version: '1', host: 'api.test', base_url: 'https://api.test/',
+                                                  version_url: 'https://api.test/v1/', description: {},
+                                                  resource_path: ['widget'], action_name: 'update', action:, sample:, detail: :thorough)
+    client_type = Class.new(HaveAPI::Client::Client) { attr_accessor :widget }
+    client = instance_double(client_type, setup: nil, authenticate: nil)
+    allow(HaveAPI::Client).to receive(:new).and_return(client)
+    failure_action = Object.new
+    def failure_action.client_message(_key, **values)
+      values[:message] || 'validation failure'
+    end
+
+    def failure_action.name
+      'update'
+    end
+    response = HaveAPI::Client::Response.new(failure_action, { status: false, message: 'API failure', errors: { count: ['bad'] } })
+    errors = [HaveAPI::Client::ValidationError.new(failure_action, { count: ['bad'] }),
+              HaveAPI::Client::ActionFailed.new(response),
+              HaveAPI::Client::Authentication::AuthenticationFailed.new('authentication failure'),
+              HaveAPI::Client::ProtocolError.new('protocol failure'), RestClient::Exception.new,
+              JSON::ParserError.new('invalid JSON')]
+    source = HaveAPI::ClientExamples::RubyClient.render(:init, context:).fetch(:code)
+    errors.each do |error|
+      allow(client).to receive(:setup).and_raise(error)
+      expect { execute_ruby(source) }.to output(/./).to_stderr
+    end
+    expect(client).to have_received(:setup).exactly(errors.length).times
+    allow(client).to receive(:setup).and_return(nil)
+    allow(client).to receive(:authenticate).and_raise(errors[2])
+    auth = HaveAPI::ClientExamples::RubyClient.render(:auth, context:, auth_method: :basic, auth_description: {}).fetch(:code)
+    expect { execute_ruby(auth) }.to output(/authentication failure/).to_stderr
+    allow(client).to receive(:setup).and_return(nil)
+    widget_type = Class.new do
+      def update(*); end
+    end
+    widget = instance_double(widget_type)
+    allow(client).to receive(:widget).and_return(widget)
+    allow(widget).to receive(:update).and_raise(errors[0])
+    action_source = HaveAPI::ClientExamples::RubyClient.render(:example, context:).fetch(:code)
+    expect { execute_ruby(action_source) }.to output(/validation failure/).to_stderr
+    allow(client).to receive(:setup).and_raise(RuntimeError, 'unknown dependency failure')
+    expect { execute_ruby(source) }.to raise_error(RuntimeError, 'unknown dependency failure')
+    expect(source.index('ValidationError')).to be < source.index('ActionFailed')
+    expect(source).to include('error.response.is_a?(HaveAPI::Client::Response)')
+  end
+
+  it 'runs PHP handlers with real framework error objects and rethrows unknown dependency exceptions' do
+    root = File.expand_path('../../../..', __dir__)
+    renderer = HaveAPI::ClientExamples::PhpClient.new(*client_args)
+    prefix = <<~PHP
+      <?php
+      require #{renderer.value(File.join(root, 'clients/php/src/Client/Exception/Base.php'))};
+      require #{renderer.value(File.join(root, 'clients/php/src/Client/Exception/ValidationError.php'))};
+      require #{renderer.value(File.join(root, 'clients/php/src/Client/Exception/ActionFailed.php'))};
+      require #{renderer.value(File.join(root, 'clients/php/src/Client/Exception/AuthenticationFailed.php'))};
+      require #{renderer.value(File.join(root, 'clients/php/src/Client/Exception/ProtocolError.php'))};
+      require #{renderer.value(File.join(root, 'clients/php/src/Client/Response.php'))};
+      $wire = (object) ['code' => 400, 'body' => (object) ['status' => false, 'message' => 'API failure', 'errors' => ['count' => ['bad']]]];
+      $response = new \\HaveAPI\\Client\\Response(null, $wire, 0);
+    PHP
+    errors = [
+      'new \\HaveAPI\\Client\\Exception\\ValidationError("update", ["count" => ["bad"]])',
+      'new \\HaveAPI\\Client\\Exception\\ActionFailed($response, "API failure")',
+      'new \\HaveAPI\\Client\\Exception\\AuthenticationFailed("authentication failure")',
+      'new \\HaveAPI\\Client\\Exception\\ProtocolError("protocol failure")'
+    ]
+    errors.each do |error|
+      script = prefix + "$failure = #{error};\n" + renderer.with_error_handling('throw $failure;')
+      output, status = Open3.capture2e('php', stdin_data: script)
+      expect(status).to be_success, output
+      expect(output).not_to be_empty
+    end
+    script = "#{prefix}$failure = new \\RuntimeException('unknown dependency');\ntry {\n" \
+             "#{renderer.with_error_handling('throw $failure;')}" \
+             "} catch (\\RuntimeException $error) { echo 'UNKNOWN_PROPAGATED'; }\n"
+    output, status = Open3.capture2e('php', stdin_data: script)
+    expect(status).to be_success, output
+    expect(output).to include('UNKNOWN_PROPAGATED')
+    context = HaveAPI::ClientExample::Context.new(version: '1', host: 'api.test', base_url: 'https://api.test/',
+                                                  version_url: 'https://api.test/v1/', description: {}, detail: :thorough)
+    source = HaveAPI::ClientExamples::PhpClient.render(:auth, context:, auth_method: :oauth2, auth_description: {}).fetch(:code)
+    status, output = syntax_check(%w[php -l], "<?php\n#{source}", '.php')
+    expect(status).to be_success, output
+    expect(source).to include('session_start()', 'requestAuthorizationCode()', 'requestAccessToken()', "$_SESSION['access_token']")
+    expect(source).not_to include('Throwable', 'getResponse()->http_status')
+  end
+
+  it 'keeps Ruby token-login literals truthy through the actual runtime option filter' do
+    fields = { user: { type: 'String', required: true }, password: { type: 'String', required: true },
+               enabled: { type: 'Boolean', required: true },
+               custom: { type: 'Custom', nullable: true, required: false,
+                         validators: { include: { values: [nil, 'public-choice'] } } } }
+    continuation = { confirmation: { type: 'Boolean', required: true, validators: { accept: { value: false } } },
+                     empty: { type: 'Custom', nullable: true, required: false, validators: { accept: { value: nil } } } }
+    description = { resources: { token: { actions: { request: { input: { parameters: fields } },
+                                                     verify: { input: { parameters: continuation } } } } } }
+    definitions = HaveAPI::Params.new(:input, nil)
+    definitions.layout = :hash
+    definitions.namespace = false
+    definitions.custom(:custom, nullable: true, required: false, default: 'public-choice', fill: true, choices: [nil, 'public-choice'])
+    expect(definitions.params.first).to be_optional
+    expect(definitions.params.first).to be_nullable
+    expect(definitions.validate({ custom: nil })).to eq(custom: nil)
+    expect(definitions.validate({})).to eq(custom: 'public-choice')
+    before = Marshal.dump(description)
+    renderer = HaveAPI::ClientExamples::RubyClient.new(*client_args)
+    options = renderer.send(:auth_token_credentials, description).transform_keys(&:to_sym)
+    expect(options).to include(enabled: true, custom: 'public-choice')
+    finite = Marshal.load(Marshal.dump(description))
+    finite[:resources][:token][:actions][:request][:input][:parameters][:enabled][:validators] = { include: { values: [false, true] } }
+    expect(renderer.send(:auth_token_credentials, finite)).to include('enabled' => true)
+    provider = HaveAPI::Client::Authentication::Token.allocate
+    provider.instance_variable_set(:@opts, options)
+    provider.instance_variable_set(:@desc, description)
+    allow(provider).to receive(:login_step).and_return(:done)
+    provider.send(:request_token)
+    expect(provider).to have_received(:login_step).with(:request, include(enabled: true, custom: 'public-choice'))
+    expect(renderer.send(:auth_token_continuations, description).fetch('verify')).to eq('confirmation' => false, 'empty' => nil)
+    expect(Marshal.dump(description)).to eq(before)
+    php = HaveAPI::ClientExamples::PhpClient.new(*client_args)
+    expect(php.send(:auth_token_credentials, description)).to include('enabled' => false, 'custom' => 'public-choice')
+    root = File.expand_path('../../../..', __dir__)
+    script = <<~PHP
+      <?php
+      require #{php.value(File.join(root, 'clients/php/src/Client/Authentication/Base.php'))};
+      require #{php.value(File.join(root, 'clients/php/src/Client/Authentication/Token.php'))};
+      new class(#{php.value(php.send(:auth_token_credentials, description))}) extends \\HaveAPI\\Client\\Authentication\\Token {
+          public function __construct($options) { $this->opts = $options; $this->requestToken(); }
+          protected function getRequestCredentials() { return ["user", "password", "enabled", "custom"]; }
+          protected function runAuthentication($action, $input) { echo json_encode($input); }
+      };
+    PHP
+    output, status = Open3.capture2e('php', stdin_data: script)
+    expect(status).to be_success, output
+    expect(JSON.parse(output)).to include('enabled' => false, 'custom' => 'public-choice')
+    # The same real PHP method loses explicit null before the request boundary.
+    dropped_script = script.sub(php.value(php.send(:auth_token_credentials, description)),
+                                php.value({ 'user' => 'user', 'password' => 'secret', 'enabled' => false, 'custom' => nil }))
+    dropped_output, dropped_status = Open3.capture2e('php', stdin_data: dropped_script)
+    expect(dropped_status).to be_success, dropped_output
+    dropped = JSON.parse(dropped_output)
+    expect(dropped).to include('enabled' => false)
+    expect(dropped).not_to have_key('custom')
+
+    js = HaveAPI::ClientExamples::JsClient.new(*client_args)
+    expect(js.send(:auth_token_credentials, description)).to include('enabled' => false, 'custom' => nil)
+    expect(HaveAPI::ClientExamples::PythonClient.new(*client_args).send(:auth_token_credentials, description))
+      .to include('enabled' => false, 'custom' => nil)
+  end
+
+  it 'limits required Ruby false and optional nullable Ruby/PHP null-only login choices' do
+    ruby = HaveAPI::ClientExamples::RubyClient
+    php = HaveAPI::ClientExamples::PhpClient
+    boolean = { type: 'Boolean', required: true, validators: { accept: { value: false } } }
+    custom = { type: 'Custom', nullable: true, required: false, validators: { include: { values: [nil] } } }
+    context = HaveAPI::ClientExample::Context.new(version: '1', host: 'api.test', base_url: 'https://api.test/',
+                                                  version_url: 'https://api.test/v1/', description: {})
+    null_acceptance = custom.merge(validators: { accept: { value: nil } })
+    [[ruby, boolean], [ruby, custom], [php, custom], [ruby, null_acceptance], [php, null_acceptance],
+     [ruby, boolean.merge(required: false)]].each do |renderer, parameter|
+      description = { resources: { token: { actions: { request: { input: { parameters: { required_input: parameter } } } } } } }
+      %i[simple thorough].each do |detail|
+        result = renderer.render(:auth, context: context.with(detail:), auth_method: :token, auth_description: description)
+        expect(result).to include(status: :limitation)
+        expect(result[:reason]).to include('cannot send')
+      end
+    end
+    fields = { resources: { token: { actions: { request: { input: { parameters: { enabled: boolean } } } } } } }
+    expect(php.render(:auth, context:, auth_method: :token, auth_description: fields)[:status]).to eq(:code)
+  end
 end

data/spec/client_examples/ts_generated_client_spec.rb

@@ -2,6 +2,7 @@ require 'spec_helper'
 
 class TypeScriptDocumentationAdapterFixture
   def render(kind:, context:, mode:, auth_method: nil, auth_description: nil); end
+  def detail_levels_for(kind:, context:, result:, mode:, auth_method: nil, auth_description: nil); end
 end
 
 describe HaveAPI::ClientExamples::TsGeneratedClient do
@@ -17,12 +18,24 @@ describe HaveAPI::ClientExamples::TsGeneratedClient do
 
   it 'adds a separate generated variant while preserving dynamic TypeScript identifiers' do
     expect(described_class.id).to eq('typescript-generated')
-    expect(described_class.label).to eq('TypeScript (generated)')
+    expect(described_class.label).to eq('TypeScript API client')
     expect(described_class.code).to eq(:typescript)
     expect(HaveAPI::ClientExamples::TsClient.id).to eq('typescript-callback')
     expect(HaveAPI::ClientExamples::TsAsyncClient.id).to eq('typescript-async')
   end
 
+  it 'delegates meaningful-detail queries with the rendered result, authentication and native mode' do
+    result = { status: :code, code: 'API client' }.freeze
+    allow(adapter).to receive(:detail_levels_for).and_return([:simple].freeze)
+    expect(described_class.detail_levels_for(:auth, context:, result:, auth_method: :basic, auth_description: {})).to eq([:simple])
+    expect(adapter).to have_received(:detail_levels_for).with(kind: :auth, context:, result:, mode: :async,
+                                                              auth_method: :basic, auth_description: {})
+    allow(adapter).to receive(:detail_levels_for).and_return(%i[simple thorough].freeze)
+    expect(described_class.detail_levels_for(:example, context:, result:)).to eq(%i[simple thorough])
+    allow(adapter).to receive(:detail_levels_for).and_return(nil)
+    expect { described_class.detail_levels_for(:example, context:, result:) }.to raise_error(ArgumentError)
+  end
+
   it 'is available only for a matching optional profile' do
     expect(described_class.available?(nil)).to be(false)
     expect(described_class.available?(context.with(profile: nil))).to be(false)
@@ -42,7 +55,7 @@ describe HaveAPI::ClientExamples::TsGeneratedClient do
 
   it 'binds only the supplied authorized sample and preserves limitations' do
     sample = { request: { label: 'public' } }
-    result = { status: :limitation, reason: 'The saved SDK does not represent this sample.' }.freeze
+    result = { status: :limitation, reason: 'The saved API client does not represent this sample.' }.freeze
     allow(adapter).to receive(:render).and_return(result)
     renderer = described_class.new('example.test', 'https://example.test/', '1.0').with_context(context)
     expect(renderer.example(sample)).to eq(result)

data/spec/client_examples/typescript_profiles_spec.rb

@@ -58,7 +58,7 @@ describe HaveAPI::ClientExample::Profiles do
     expect(server).to have_received(:describe_version).once
   end
 
-  it 'loads a saved SDK once at registration with explicit package and generator versions' do
+  it 'loads a saved API client once at registration with explicit package and generator versions' do
     File.write(snapshot_path, JSON.generate(api_version: '1.0'))
     profiles.register('1.0', typescript: { package_name: 'widget-client', package_version: '1.2.3-beta.1+build.4',
                                            snapshot_path:, generator_version: HaveAPI::VERSION })

data/spec/documentation/auth_filtering_spec.rb

@@ -278,15 +278,20 @@ describe DocAuthFilteringSpec do
     end
 
     it 'does not retain privileged sample data across HTML documentation requests' do
-      login('admin', 'pass')
-      get '/v1/'
+      require_relative '../../test_support/documentation_oauth_fixture'
+      @api = HaveAPI::Server.new(get_opt(:api_module))
+      @api.use_version(1)
+      users = %w[admin user].to_h { |name| [name, DocAuthFilteringSpec::User.new(1, name)] }
+      fixture = DocumentationOAuthFixture.configure(@api, users: { 1 => users })
+      @api.mount('/')
+      get "#{fixture.origin}/v1/?resource=secure", {}, 'HTTP_COOKIE' => fixture.header_for(@api, version: 1, token: 'admin')
       expect(last_response.status).to eq(200)
       expect(last_response.body).to include('ADMIN_ONLY_RESULT')
 
-      login('user', 'pass')
-      get '/v1/'
+      get "#{fixture.origin}/v1/?resource=secure", {}, 'HTTP_COOKIE' => fixture.header_for(@api, version: 1, token: 'user')
       expect(last_response.status).to eq(200)
       expect(last_response.body).not_to include('ADMIN_ONLY_RESULT')
+      expect(fixture.lookups).to eq([[1, 'admin'], [1, 'user']])
     end
   end
 end