haveapi 0.31.1 → 0.32.0

data/spec/client_examples/dynamic_acceptance_spec.rb

@@ -3,37 +3,168 @@ require 'rack/mock'
 require_relative 'dynamic_acceptance'
 
 RSpec.describe DynamicDocumentationAcceptance do
-  it 'extracts actual six-language HTML panels from the mounted fixture' do
-    request = Rack::MockRequest.new(DynamicDocumentationAPI.build.app)
-    response = request.get('http://example.test/mount/v2/', 'HTTP_HOST' => 'example.test')
-    expect(response.status).to eq(200), response.body
-    panels = described_class.extract(response.body)
+  let(:trace) { StringIO.new }
+  let(:request) do
+    Rack::MockRequest.new(DynamicDocumentationAPI::RequestTrace.new(DynamicDocumentationAPI.build.app, output: trace))
+  end
+
+  def receipt_snapshot
+    JSON.parse(request.get('/__acceptance_receipts').body)
+  end
+
+  def setup_panel(provider = nil, detail: :simple)
+    { id: 'fixture-panel', group: provider ? "auth-#{provider}-examples" : 'init-examples', detail: }
+  end
+
+  def json_post(path, payload)
+    request.post(path, 'CONTENT_TYPE' => 'application/json', input: JSON.generate(payload))
+  end
+
+  it 'extracts the complete actual matrix with eight singleton and28 requested thorough panels' do
+    pages = described_class::PAGES.values.map do |query|
+      response = request.get("http://example.test/mount/v2/#{query}", 'HTTP_HOST' => 'example.test')
+      expect(response.status).to eq(200), response.body
+      response.body
+    end
+    panels = pages.flat_map { |body| described_class.extract(body) }
+    expect { described_class.validate_coverage!(panels) }.not_to raise_error
+    expect(panels.length).to eq(36)
+    expect(panels.count { |panel| panel[:detail] == :simple }).to eq(8)
+    expect(panels.count { |panel| panel[:detail] == :thorough }).to eq(28)
+    simple = pages.flat_map { |body| described_class.extract(body, detail: :simple) }
+    expect(simple.length).to eq(36)
+    expect(simple).to all(include(detail: :simple, requested_detail: :simple))
+    overlap = panels.map { |panel| panel[:id] } & simple.map { |panel| panel[:id] }
+    expect(overlap.length).to eq(8)
     described_class::VARIANTS.each do |variant|
       selected = panels.select { |panel| panel[:variant] == variant }
-      expect(selected.map { |panel| panel[:id].split('-').first }).to include('init', 'auth', 'example')
-      expect(selected.count { |panel| panel[:id].start_with?('example-') }).to eq(2)
+      expect(selected.map { |panel| panel[:group] }.sort).to eq(described_class::GROUPS.sort)
       expect(selected.last[:source]).to include('http://example.test/mount/')
       expect(selected.last[:source]).not_to include('"')
+      expect(selected).to all(include(requested_detail: :thorough))
     end
+    expect { described_class.validate_coverage!(panels.drop(1)) }.to raise_error(/Incomplete/)
+    expect { described_class.validate_coverage!(panels + [panels.first]) }.to raise_error(/Incomplete/)
+  end
+
+  it 'fails malformed missing duplicate or undeclared groups and selected code instead of skipping coverage' do
+    html = request.get('/mount/v2/', 'HTTP_HOST' => 'example.test').body
+    map = html.match(/data-example-details="([^"]+)"/)[1]
+    missing = JSON.parse(CGI.unescapeHTML(map)).except('javascript-callback')
+    variants = [
+      html.sub(/data-example-details="[^"]+"/, ''),
+      html.sub(map, CGI.escapeHTML('{broken')),
+      html.sub(map, CGI.escapeHTML(JSON.generate(missing))),
+      html.sub(map, CGI.escapeHTML('{"javascript-callback":["simple"],"javascript-callback":["simple"]}')),
+      html.sub(map, map.sub('simple', 'unknown')),
+      html.sub(/(data-client="javascript-callback"[^>]*data-detail=")simple"/, '\\1other"'),
+      html.sub(%r{(<details[^>]*data-client="javascript-callback"[^>]*>.*?</details>)}m) { |panel| panel * 2 },
+      html.sub(%r{(<details[^>]*data-client="javascript-callback"[^>]*>).*?</details>}m,
+               '\\1<p class="client-limitation">unsupported</p></details>')
+    ]
+    variants.each_with_index do |invalid, index|
+      expect { described_class.extract(invalid) }.to raise_error(StandardError), "Malformed fixture #{index} was accepted"
+    end
+    group = html.match(%r{<div[^>]*data-example data-example-details=.*?</div>}m)[0]
+    expect { described_class.extract(html + group) }.to raise_error(/Duplicate example group/)
+    expect { described_class.extract(html, detail: :other) }.to raise_error(/Invalid requested/)
+  end
+
+  it 'requires authenticated mounted discovery for the correct provider on each independent run' do
+    before = receipt_snapshot
+    expect(request.options('/mount/v2/').status).to eq(200)
+    anonymous = receipt_snapshot
+    delta = described_class.receipt_delta(before, anonymous)
+    expect { described_class.verify_completion!(setup_panel, '', delta) }.not_to raise_error
+    expect { described_class.verify_completion!(setup_panel('basic'), '', delta) }.to raise_error(/did not complete/)
+    headers = { 'basic' => { 'HTTP_AUTHORIZATION' => "Basic #{['user:secret'].pack('m0')}" },
+                'token' => { 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'example-token' },
+                'oauth2' => { 'HTTP_X_FIXTURE_OAUTH2' => 'example-access-token' } }
+    headers.each do |provider, credentials|
+      before = receipt_snapshot
+      expect(request.options('/mount/v2/', credentials).status).to eq(200)
+      delta = described_class.receipt_delta(before, receipt_snapshot)
+      expect { described_class.verify_completion!(setup_panel(provider), '', delta) }.not_to raise_error unless provider == 'token'
+      expect { described_class.verify_completion!(setup_panel(provider), 'Discovery or authentication failed', delta) }
+        .to raise_error(/Failed callback/)
+      expect { described_class.verify_completion!(setup_panel(provider, detail: :thorough), '', delta) }
+        .to raise_error(provider == 'token' ? /Token challenge/ : /Missing completion output/)
+      expect { described_class.verify_completion!(setup_panel(provider), '', described_class.receipt_delta(receipt_snapshot, receipt_snapshot)) }
+        .to raise_error(/did not complete/)
+    end
+    before = receipt_snapshot
+    request.options('/mount/v2/', 'HTTP_AUTHORIZATION' => "Basic #{['user:wrong-secret'].pack('m0')}")
+    rejected = described_class.receipt_delta(before, receipt_snapshot)
+    expect { described_class.verify_completion!(setup_panel('basic'), '', rejected) }.to raise_error(/did not complete/)
+    expect(rejected['events']).to include(include('type' => 'authentication', 'provider' => 'basic', 'authenticated' => false))
+    expect(trace.string).not_to include('wrong-secret', 'secret', 'example-token', 'example-access-token', 'Authorization')
+  end
+
+  it 'requires request then verification then authenticated discovery inside each token-authentication program' do
+    before = receipt_snapshot
+    response = json_post('/mount/_auth/token/tokens', token: { user: 'user', password: 'secret', lifetime: 'fixed' })
+    expect(response.status).to eq(200), response.body
+    incomplete = described_class.receipt_delta(before, receipt_snapshot)
+    expect { described_class.verify_completion!(setup_panel('token'), '', incomplete) }.to raise_error(/did not complete/)
+    response = json_post('/mount/_auth/token/tokens/verify', token: { token: 'fixture-challenge', code: 'code' })
+    expect(response.status).to eq(200), response.body
+    request.options('/mount/v2/', 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'example-token')
+    delta = described_class.receipt_delta(before, receipt_snapshot)
+    expect { described_class.verify_completion!(setup_panel('token'), '', delta) }.not_to raise_error
+    expect { described_class.verify_completion!(setup_panel('token'), '', incomplete) }.to raise_error(/did not complete/)
+    before = receipt_snapshot
+    json_post('/mount/_auth/token/tokens/verify', token: { token: 'fixture-challenge', code: 'rejected-code' })
+    request.options('/mount/v2/', 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'example-token')
+    rejected = described_class.receipt_delta(before, receipt_snapshot)
+    expect { described_class.verify_completion!(setup_panel('token'), '', rejected) }.to raise_error(/Token challenge did not complete/)
+    expect(rejected['events']).to include(include('type' => 'token_verification_rejected'))
+    expect(JSON.generate(delta['events'])).not_to include('user', 'secret', 'example-token', 'code')
+    expect(trace.string).not_to include('user', 'secret', 'example-token', 'code', 'rejected-code')
   end
 
   it 'records real success and failure request values without source rewriting' do
-    request = Rack::MockRequest.new(DynamicDocumentationAPI.build.app)
+    before = receipt_snapshot
     payload = { widget: { name: '', enabled: false, count: 0, nullable: nil, payload: DynamicDocumentationAPI::PAYLOAD } }
     headers = {
       'CONTENT_TYPE' => 'application/json',
-      'HTTP_AUTHORIZATION' => "Basic #{['fixture-user:fixture-password'].pack('m0')}",
+      'HTTP_AUTHORIZATION' => "Basic #{['user:secret'].pack('m0')}",
       input: JSON.generate(payload)
     }
     path = 'http://example.test/mount/v2/parents/7/children/name%20with%20space'
+    headers.delete('HTTP_AUTHORIZATION')
+    headers['HTTP_X_HAVEAPI_AUTH_TOKEN'] = 'example-token'
+    request.options('/mount/v2/', 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'example-token')
     response = request.post(path, headers)
     expect(response.status).to eq(200), response.body
     expect(JSON.parse(response.body).fetch('status')).to be(true)
     expect(DynamicDocumentationAPI.receipts.last[:input][:payload]).to eq(DynamicDocumentationAPI::PAYLOAD)
+    delta = described_class.receipt_delta(before, receipt_snapshot)
+    panel = { id: 'success-panel', group: described_class::GROUPS[-2], detail: :thorough }
+    expect { described_class.verify_completion!(panel, 'DOC_SUCCESS', delta) }.not_to raise_error
+    expect { described_class.verify_completion!(panel, '', delta) }.to raise_error(/Wrong result/)
+    expect { described_class.verify_completion!(panel, 'DOC_SUCCESS', delta.merge('actions' => delta['actions'] * 2)) }
+      .to raise_error(/did not execute once/)
+    before = receipt_snapshot
+    request.options('/mount/v2/', 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'example-token')
     payload[:widget][:count] = -1
     response = request.post(path, headers.merge(input: JSON.generate(payload)))
     expect(response.status).to eq(400), response.body
     expect(JSON.parse(response.body).fetch('message')).to eq('DOC_FAILURE')
+    delta = described_class.receipt_delta(before, receipt_snapshot)
+    panel[:group] = described_class::GROUPS.last
+    expect { described_class.verify_completion!(panel, 'DOC_FAILURE', delta) }.not_to raise_error
+  end
+
+  it 'rejects malformed or rewound receipt snapshots and rejected token-login completion' do
+    before = receipt_snapshot
+    json_post('/mount/_auth/token/tokens', token: { user: 'user', password: 'wrong-secret', lifetime: 'fixed' })
+    after = receipt_snapshot
+    delta = described_class.receipt_delta(before, after)
+    expect(delta['events']).to include(include('type' => 'token_request_rejected'))
+    expect { described_class.verify_completion!(setup_panel('token'), '', delta) }.to raise_error(/did not complete/)
+    expect { described_class.receipt_delta(after, before) }.to raise_error(/changed before/)
+    expect { described_class.receipt_delta([], after) }.to raise_error(/Invalid fixture receipt/)
+    expect(trace.string).not_to include('wrong-secret', 'secret')
   end
 
   it 'preserves subprocess output before reporting a nonzero execution failure' do
@@ -46,20 +177,6 @@ RSpec.describe DynamicDocumentationAcceptance do
     end
   end
 
-  it 'preserves separate existing-token and challenge output before completion assertions' do
-    Dir.mktmpdir('haveapi-doc-output-') do |directory|
-      command = ['ruby', '-e', 'puts ENV.key?("HAVEAPI_TOKEN") ? "Authenticated" : "Discovery or authentication failed"']
-      path = File.join(directory, 'example-12.log')
-      challenge_path = File.join(directory, 'example-12-challenge.log')
-      result = described_class.run!(*command, chdir: directory, env: { 'HAVEAPI_TOKEN' => 'fixture-token' }, log_path: path)
-      challenge = described_class.run!(*command, chdir: directory, env: { 'HAVEAPI_TOKEN' => nil }, log_path: challenge_path)
-      expect(File.read(path)).to eq(result)
-      expect(File.read(challenge_path)).to eq(challenge)
-      expect(result).to include('Authenticated')
-      expect(challenge).to include('Discovery or authentication failed')
-    end
-  end
-
   it 'traces failed mounted routes without headers, query strings or request bodies' do
     output = StringIO.new
     app = DynamicDocumentationAPI::RequestTrace.new(DynamicDocumentationAPI.build.app, output:)

data/spec/client_examples/dynamic_fixture.rb

@@ -29,8 +29,9 @@ module DynamicExampleFixture
   end
 
   def token_description
-    { resources: { token: { actions: { 'request' => { input: { parameters: {
-      'login-name' => { type: 'String' }, password: { type: 'String' }, lifetime: { type: 'String' }
-    } } } } } } }
+    request = { 'login-name' => { type: 'String' }, password: { type: 'String' }, lifetime: { type: 'String' } }
+    verify = { token: { type: 'String', required: true }, code: { type: 'String', required: true } }
+    { resources: { token: { actions: { 'request' => { input: { parameters: request } },
+                                       'verify' => { input: { parameters: verify } } } } } }
   end
 end

data/spec/client_examples/dynamic_js_spec.rb

@@ -39,9 +39,10 @@ RSpec.describe HaveAPI::ClientExamples::JsClient do
 
   it 'renders complete syntax-valid initialization, authentication and hostile action programs' do
     renderers.each do |renderer|
-      results = [renderer.render(:init, context: dynamic_context), renderer.render(:example, context: dynamic_context)]
+      context = dynamic_context(detail: :thorough)
+      results = [renderer.render(:init, context:), renderer.render(:example, context:)]
       %i[basic token oauth2].each do |method|
-        results << renderer.render(:auth, context: dynamic_context, auth_method: method, auth_description: token_description)
+        results << renderer.render(:auth, context:, auth_method: method, auth_description: token_description)
       end
       results.each do |result|
         expect(result[:status]).to eq(:code), result.inspect
@@ -60,7 +61,7 @@ RSpec.describe HaveAPI::ClientExamples::JsClient do
       expect(source).to include('["enabled"]: false', '["count"]: 0', '["nullable"]: null', '["__proto__"]:')
       expect(source).to include('new\\"\\n</script>')
       if renderer.id.end_with?('-async')
-        expect(source).to include('.resource("constructor").resource("resources").action(', 'result.value', 'result.response.meta')
+        expect(source).to include('.resource("constructor").resource("resources").action(', 'result.value')
       else
         expect(source).to include('CallbackClient.findResource', 'CallbackClient.findAction', 'action.directInvoke', 'reply.message()', 'reply.envelope.errors')
       end
@@ -72,14 +73,22 @@ RSpec.describe HaveAPI::ClientExamples::JsClient do
     Dir.mktmpdir('haveapi-ts-docs-') do |directory|
       files = []
       [HaveAPI::ClientExamples::TsClient, HaveAPI::ClientExamples::TsAsyncClient].each_with_index do |renderer, index|
-        results = [renderer.render(:init, context: dynamic_context), renderer.render(:example, context: dynamic_context)]
-        %i[basic token oauth2].each do |method|
-          results << renderer.render(:auth, context: dynamic_context, auth_method: method, auth_description: token_description)
-        end
-        results.each_with_index do |result, number|
-          path = File.join(directory, "#{index}-#{number}.ts")
-          File.write(path, result.fetch(:code))
-          files << path
+        %i[simple thorough].each do |detail|
+          context = dynamic_context(detail:)
+          results = [renderer.render(:init, context:), renderer.render(:example, context:)]
+          %i[basic token oauth2].each do |method|
+            results << renderer.render(:auth, context:, auth_method: method, auth_description: token_description)
+          end
+          results.each_with_index do |result, number|
+            source = result.fetch(:code)
+            if detail == :simple && number == 1
+              client = renderer.id.end_with?('-async') ? 'AsyncClient' : 'CallbackClient'
+              source = "import { #{client} } from \"haveapi-client\";\ndeclare const api: #{client};\n#{source}"
+            end
+            path = File.join(directory, "#{index}-#{detail}-#{number}.ts")
+            File.write(path, source)
+            files << path
+          end
         end
       end
       options = { strict: true, noEmit: true, target: 'ES2020', module: 'ESNext', moduleResolution: 'node',

data/spec/client_examples/dynamic_metadata_spec.rb

@@ -49,4 +49,73 @@ RSpec.describe HaveAPI::ClientExamples::DynamicHelpers do
       expect(renderer.render(:example, context:)[:status]).to eq(:code)
     end
   end
+
+  it 'uses only public typed literals and advertised finite machine choices for token inputs' do
+    description = token_description
+    fields = description[:resources][:token][:actions]['request'][:input][:parameters]
+    fields[:user] = { type: 'String', required: true, default: 'PRIVATE_USER' }
+    fields[:password][:default] = 'PRIVATE_PASSWORD'
+    fields[:count] = { type: 'Integer', required: true, default: 99 }
+    fields[:enabled] = { type: 'Boolean', required: true, validators: { accept: { value: true, message: 'PRIVATE_PROSE' } } }
+    fields[:scope] = { type: 'String', required: true, validators: { include: { values: { 'all' => 'PRIVATE_LABEL' } } } }
+    fields[:resource] = { type: 'Resource', required: true }
+    fields[:timestamp] = { type: 'Datetime', required: true }
+    fields[:custom] = { type: 'Custom', required: true }
+    fields[:interval] = { type: 'Integer', required: true }
+    before = Marshal.dump(description)
+    renderers.each do |renderer|
+      result = renderer.render(:auth, context: dynamic_context, auth_method: :token, auth_description: description)
+      expect(result[:status]).to eq(:code), result.inspect
+      expect(result[:code]).to include('secret', 'user', 'fixed', 'all', '2026-01-01T00:00:00Z')
+      expect(result[:code]).not_to include('PRIVATE_', 'os.environ', 'credential(', 'HAVEAPI_', 'node:process')
+    end
+    expect(Marshal.dump(description)).to eq(before)
+    helper = HaveAPI::ClientExamples::JsClient.new('api.test', 'https://api.test/', '2')
+    inputs = helper.send(:auth_token_credentials, description)
+    expect(inputs).to include('user' => 'user', 'password' => 'secret', 'count' => 1, 'enabled' => true,
+                              'scope' => 'all', 'resource' => 1, 'custom' => {}, 'interval' => 1, 'lifetime' => 'fixed')
+  end
+
+  it 'limits unsupported required types and input shapes instead of guessing defaults or dropping fields' do
+    descriptions = []
+    description = token_description
+    description[:resources][:token][:actions]['request'][:input][:parameters][:hidden] = {
+      type: 'Unsupported', required: true, default: 'PRIVATE_DEFAULT'
+    }
+    descriptions << description
+    description = token_description
+    description[:resources][:token][:actions]['verify'][:input][:parameters][:hidden] = {
+      type: 'Unsupported', required: true, default: 'PRIVATE_DEFAULT'
+    }
+    descriptions << description
+    description = token_description
+    description[:resources][:token][:actions]['request'][:input][:layout] = :object_list
+    descriptions << description
+    renderers.each do |renderer|
+      descriptions.each do |desc|
+        result = renderer.render(:auth, context: dynamic_context, auth_method: :token, auth_description: desc)
+        expect(result).to include(status: :limitation)
+        expect(result.inspect).not_to include('PRIVATE_DEFAULT')
+      end
+    end
+  end
+
+  it 'uses actual continuation action arguments and rejects unknown continuation or input names' do
+    renderer = HaveAPI::ClientExamples::JsClient.new('api.test', 'https://api.test/', '2')
+    options = renderer.token_login_options(token_description)
+    script = <<~JS
+      const assert = require('node:assert/strict');
+      const options = #{options};
+      assert.deepEqual(options.callback('verify', {code: {}}), {code: 'code'});
+      assert.throws(() => options.callback('missing', {code: {}}), /Unknown authentication continuation/);
+      assert.throws(() => options.callback('verify', {unexpected: {}}), /Unknown authentication input/);
+    JS
+    output, status = Open3.capture2e('node', '-e', script)
+    expect(status).to be_success, output
+    renderers.grep(Class).each do |client|
+      source = client.render(:auth, context: dynamic_context, auth_method: :token, auth_description: token_description).fetch(:code)
+      expect(source).not_to include('os.environ', 'HAVEAPI_', 'step.action')
+      expect(source).to include(client.code == :python ? 'step.next_action' : '(action, parameters)')
+    end
+  end
 end

data/spec/client_examples/dynamic_mounted_paths_spec.rb

@@ -6,7 +6,7 @@ require_relative '../../test_support/dynamic_documentation_api'
 RSpec.describe DynamicDocumentationAPI do
   it 'uses real mounted descriptor routes for callback and async token challenges and nested actions' do
     request = Rack::MockRequest.new(described_class.build.app)
-    headers = { 'HTTP_AUTHORIZATION' => "Basic #{['fixture-user:fixture-password'].pack('m0')}" }
+    headers = { 'HTTP_AUTHORIZATION' => "Basic #{['user:secret'].pack('m0')}" }
     envelope = JSON.parse(request.options('http://example.test/mount/v2/', headers).body)
     model = envelope.fetch('response')
     token = model.fetch('authentication').fetch('token').fetch('resources').fetch('token').fetch('actions')
@@ -17,14 +17,16 @@ RSpec.describe DynamicDocumentationAPI do
     post = lambda do |path, body, extra = {}|
       response = request.post("http://example.test#{path}", extra.merge('CONTENT_TYPE' => 'application/json', input: JSON.generate(body)))
       expect(response.status).to eq(200), response.body
-      JSON.parse(response.body)
+      payload = JSON.parse(response.body)
+      expect(payload.fetch('status')).to be(true), response.body
+      payload
     end
     challenge = post.call(token.fetch('request').fetch('path'), { token: {
-      user: 'fixture-user', password: 'fixture-password', scope: 'all', lifetime: 'renewable_auto'
+      user: 'user', password: 'secret', scope: 'all', lifetime: 'renewable_auto'
     } })
-    completed = post.call(token.fetch('verify').fetch('path'), { token: { token: 'fixture-challenge', code: '123456' } })
+    completed = post.call(token.fetch('verify').fetch('path'), { token: { token: 'fixture-challenge', code: 'code' } })
     action_path = action.fetch('path').sub('{parent_id}', '7').sub('{widget_id}', 'name%20with%20space')
-    result = post.call(action_path, { widget: params }, { 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'fixture-token' })
+    result = post.call(action_path, { widget: params }, { 'HTTP_X_HAVEAPI_AUTH_TOKEN' => 'example-token' })
     data = { envelope:, challenge:, completed:, result:, params:, action_path: }
     script = <<~JS
       const assert = require('node:assert/strict');
@@ -36,7 +38,7 @@ RSpec.describe DynamicDocumentationAPI do
       async function check() {
         const callback = new HaveAPI.CallbackClient('http://example.test/mount/', {version:'2'});
         let ready = false;
-        callback.authenticate('token', {user:'fixture-user', password:'fixture-password', scope:'all', callback: () => ({code:'123456'})},
+        callback.authenticate('token', {user:'user', password:'secret', scope:'all', callback: () => ({code:'code'})},
           (_, ok) => { ready = ok; });
         // Parse actual discovery JSON inside the bundle's VM, matching the real XHR boundary.
         assert.equal(requests[0].url, 'http://example.test/mount/v2/'); requests[0].respond(data.envelope);
@@ -47,7 +49,7 @@ RSpec.describe DynamicDocumentationAPI do
         HaveAPI.CallbackClient.findAction(resource, 'new').directInvoke(7, 'name with space', {params:data.params});
         assert.equal(requests[4].url, 'http://example.test' + data.action_path); requests[4].respond(data.result);
         const api = new HaveAPI.AsyncClient('http://example.test/mount/', {version:'2'}); api.useDescription(model);
-        const authenticating = api.authenticate('token', {user:'fixture-user', password:'fixture-password', scope:'all', onChallenge: () => ({code:'123456'})});
+        const authenticating = api.authenticate('token', {user:'user', password:'secret', scope:'all', onChallenge: () => ({code:'code'})});
         await tick(); assert.equal(requests[5].url, 'http://example.test' + auth.request.path); requests[5].respond(data.challenge);
         await tick(); assert.equal(requests[6].url, 'http://example.test' + auth.verify.path); requests[6].respond(data.completed);
         await tick(); assert.equal(requests[7].url, 'http://example.test/mount/v2/'); requests[7].respond(data.envelope); await authenticating;

data/spec/client_examples/dynamic_python_spec.rb

@@ -7,6 +7,19 @@ RSpec.describe HaveAPI::ClientExamples::PythonClient do
 
   let(:renderers) { [described_class, HaveAPI::ClientExamples::PythonAsyncClient] }
 
+  it 'separates imports, executable sync code and top-level async definitions without blank padding' do
+    %i[simple thorough].each do |detail|
+      context = dynamic_context(detail:)
+      sync = described_class.render(:init, context:).fetch(:code)
+      async = HaveAPI::ClientExamples::PythonAsyncClient.render(:init, context:).fetch(:code)
+      expect(sync).to start_with('from haveapi_client import ')
+      expect(sync).to include(detail == :simple ? "Client\n\nwith Client(" : "HaveAPIError\n\ntry:\n")
+      expect(async).to start_with("import asyncio\n\nfrom haveapi_client import ")
+      expect(async).to include("\n\n\nasync def main() -> None:\n", "\n\n\nasyncio.run(main())\n")
+      expect([sync, async]).to all(satisfy { |source| !source.start_with?("\n") && !source.end_with?("\n\n") })
+    end
+  end
+
   it 'keeps both variants available without a generated SDK profile' do
     expect(renderers.map(&:id)).to eq(%w[python-sync python-async])
     expect(renderers.map(&:order)).to eq([14, 15])
@@ -15,15 +28,28 @@ RSpec.describe HaveAPI::ClientExamples::PythonClient do
 
   it 'renders complete parseable init, auth, action and async ownership' do
     renderers.each do |renderer|
-      results = [renderer.render(:init, context: dynamic_context), renderer.render(:example, context: dynamic_context)]
+      context = dynamic_context(detail: :thorough)
+      results = [renderer.render(:init, context:), renderer.render(:example, context:)]
       %i[basic token oauth2].each do |method|
-        results << renderer.render(:auth, context: dynamic_context, auth_method: method, auth_description: token_description)
+        results << renderer.render(:auth, context:, auth_method: method, auth_description: token_description)
       end
       results.each do |result|
         expect(result[:status]).to eq(:code), result.inspect
         expect(result).to be_frozen
-        output, status = Open3.capture2e('python', '-c', 'import ast, sys; ast.parse(sys.stdin.read())', stdin_data: result[:code])
+        output, status = Open3.capture2e('python', '-c',
+                                         'import ast, json, sys; print(json.dumps([type(node).__name__ for node in ast.parse(sys.stdin.read()).body]))',
+                                         stdin_data: result[:code])
         expect(status).to be_success, output
+        statements = JSON.parse(output)
+        expect(result[:code]).not_to include('__main__')
+        if renderer.id == 'python-async'
+          expect(statements.count('AsyncFunctionDef')).to eq(1)
+          expect(statements.last).to eq('Expr')
+          expect(result[:code]).to include("\nasyncio.run(main())\n")
+        else
+          expect(statements).to include('Try')
+          expect(statements).not_to include('FunctionDef', 'AsyncFunctionDef')
+        end
         expect(result[:code]).to include('https://api.example.test/mount/', 'version="2"')
         expect(result[:code]).to include('except ActionError', 'except HaveAPIError')
       end
@@ -36,16 +62,42 @@ RSpec.describe HaveAPI::ClientExamples::PythonClient do
       expect(source).to include('.resources["constructor"].resources["resources"].actions[',
                                 'path_params={"parent_id": 7, "widget_id": "name/with space"}',
                                 '"enabled": False', '"count": 0', '"nullable": None', '"__proto__":',
-                                'print(response.data)', 'print(response.meta)')
+                                'print(response.data)')
       if renderer.id == 'python-async'
-        expect(source).to include('async with AsyncClient', 'response = await ', 'asyncio.run(main())')
+        expect(source).to include('response = await ', 'async function')
       else
-        expect(source).to include('with Client')
+        expect(source).to include('response = api.resources')
         expect(source).not_to include('await ')
       end
     end
   end
 
+  it 'keeps simple setup and authentication parseable with only the imports they use' do
+    renderers.each do |renderer|
+      init = renderer.render(:init, context: dynamic_context).fetch(:code)
+      sources = [init]
+      %i[basic token oauth2].each do |method|
+        sources << renderer.render(:auth, context: dynamic_context, auth_method: method, auth_description: token_description).fetch(:code)
+      end
+      sources.each do |source|
+        output, status = Open3.capture2e('python', '-c', 'import ast, sys; ast.parse(sys.stdin.read())', stdin_data: source)
+        expect(status).to be_success, output
+        expect(source).not_to include('__main__', 'except ', 'ActionError', 'HaveAPIError', 'print("Authenticated")')
+        if renderer.id == 'python-async'
+          expect(source).to include('async def main()', "\nasyncio.run(main())\n")
+        else
+          expect(source).not_to include('def main', 'asyncio')
+        end
+      end
+      expect(init).not_to include('import os', 'import json')
+      basic = sources[1]
+      expect(basic).to include('BasicAuth("user", "secret")')
+      expect(basic).not_to include('import json')
+      expect(sources[2]).to include('begin_token_login', 'continuations', 'step.next_action')
+      expect(sources.join).not_to include('import os', 'import json', 'os.environ')
+    end
+  end
+
   it 'retains list rows and exposes a limitation for an unnamespaced list' do
     action = dynamic_action.merge(input: { layout: :hash_list, namespace: :widgets, parameters: { name: { type: 'String' } } })
     context = dynamic_context(action:, sample: dynamic_sample.merge(request: [{ name: '' }, { name: 'second' }]))
@@ -69,7 +121,7 @@ RSpec.describe HaveAPI::ClientExamples::PythonClient do
   it 'uses real token challenge APIs and advertised login fields without printing credentials' do
     renderers.each do |renderer|
       source = renderer.render(:auth, context: dynamic_context, auth_method: :token, auth_description: token_description).fetch(:code)
-      expect(source).to include('begin_token_login', 'step.input', 'step.submit(values)', 'HAVEAPI_AUTH_login-name')
+      expect(source).to include('begin_token_login', 'step.input', 'step.submit(values)', '"login-name": "login-name"')
       expect(source).not_to include('print(step.token)', 'qwertyuiop')
     end
   end
@@ -81,15 +133,14 @@ RSpec.describe HaveAPI::ClientExamples::PythonClient do
     parameters[:interval] = { type: 'Integer', required: false }
     renderers.each do |renderer|
       source = renderer.render(:auth, context: dynamic_context, auth_method: :token, auth_description: description).fetch(:code)
-      expect(source).to include('"lifetime": json.loads(os.environ["HAVEAPI_AUTH_lifetime"])')
+      expect(source).to include('"lifetime": "fixed"')
       expect(source).not_to include('HAVEAPI_AUTH_interval', 'HAVEAPI_CHALLENGE_token', 'renewable_auto')
-      expect(source).to include('if "HAVEAPI_TOKEN" in os.environ:', 'set_auth(TokenAuth(os.environ["HAVEAPI_TOKEN"]))',
-                                'for name in step.input if name != "token"', 'step.submit(values)')
+      expect(source).to include('step.next_action', 'step.submit(values)', 'name not in values')
     end
     parameters[:interval][:required] = true
     renderers.each do |renderer|
       source = renderer.render(:auth, context: dynamic_context, auth_method: :token, auth_description: description).fetch(:code)
-      expect(source).to include('"interval": json.loads(os.environ["HAVEAPI_AUTH_interval"])')
+      expect(source).to include('"interval": 1')
     end
   end
 

data/spec/client_examples/go_spec.rb

@@ -7,6 +7,7 @@ RSpec.describe HaveAPI::ClientExamples::GoClient do
   let(:adapter) do
     contract = Class.new do
       def render(**); end
+      def detail_levels_for(**); end
     end
     instance_double(contract, render: result)
   end
@@ -22,6 +23,7 @@ RSpec.describe HaveAPI::ClientExamples::GoClient do
 
   it 'registers the frozen Go ID and requires its configured profile' do
     expect(described_class.id).to eq('go')
+    expect(described_class.label).to eq('Go API client')
     expect(described_class.code).to eq(:go)
     expect(described_class.order).to eq(16)
     expect(described_class).to be_available(context)
@@ -29,6 +31,17 @@ RSpec.describe HaveAPI::ClientExamples::GoClient do
     expect(described_class).not_to be_available(context.with(profile: Struct.new(:language).new(:rust)))
   end
 
+  it 'delegates meaningful-detail queries with the existing rendered result and native mode' do
+    allow(adapter).to receive(:detail_levels_for).and_return([:simple].freeze)
+    expect(described_class.detail_levels_for(:init, context:, result:)).to eq([:simple])
+    expect(adapter).to have_received(:detail_levels_for).with(kind: :init, context:, result:, mode: :sync,
+                                                              auth_method: nil, auth_description: nil)
+    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([:thorough])
+    expect { described_class.detail_levels_for(:example, context:, result:) }.to raise_error(ArgumentError)
+  end
+
   it 'delegates initialization without requiring the optional generator gem' do
     expect(described_class.render(:init, context:)).to eq(result)
     expect(adapter).to have_received(:render).with(kind: :init, context:, mode: :sync)
@@ -42,7 +55,7 @@ RSpec.describe HaveAPI::ClientExamples::GoClient do
   end
 
   it 'binds the selected filtered example and preserves plain limitation results' do
-    limitation = { status: :limitation, reason: 'This Go SDK input is unsupported.' }.freeze
+    limitation = { status: :limitation, reason: 'This Go API client input is unsupported.' }.freeze
     allow(adapter).to receive(:render).and_return(limitation)
     expect(described_class.render(:example, context:)).to eq(limitation)
     expect(adapter).to have_received(:render) do |**arguments|