haveapi 0.30.1 → 0.31.0

data/lib/haveapi/client_examples/ts_generated_client.rb

@@ -0,0 +1,36 @@
+require 'haveapi/client_example'
+
+module HaveAPI::ClientExamples
+  class TsGeneratedClient < HaveAPI::ClientExample
+    id 'typescript-generated'
+    label 'TypeScript (generated)'
+    code :typescript
+    order 19
+
+    def self.available?(context)
+      context&.profile&.language == :typescript
+    end
+
+    def init
+      render_documentation(:init)
+    end
+
+    def auth(method, desc)
+      render_documentation(:auth, auth_method: method, auth_description: desc)
+    end
+
+    def example(sample)
+      render_documentation(:example, rendering_context: context&.with(sample:))
+    end
+
+    private
+
+    def render_documentation(kind, rendering_context: context, **)
+      unless self.class.available?(rendering_context)
+        return { status: :limitation, reason: 'A generated TypeScript SDK documentation profile is required.' }.freeze
+      end
+
+      rendering_context.profile.adapter.render(kind:, context: rendering_context, mode: :async, **)
+    end
+  end
+end

data/lib/haveapi/documentation_clients.rb

@@ -21,7 +21,8 @@ module HaveAPI
 
       KEYS = {
         go: %i[import_path module_version description_path generator_version],
-        rust: %i[crate_name crate_version source snapshot_path generator_config_path generator_version]
+        rust: %i[crate_name crate_version source snapshot_path generator_config_path generator_version],
+        typescript: %i[package_name package_version snapshot_path generator_version]
       }.freeze
 
       def initialize
@@ -52,9 +53,12 @@ module HaveAPI
         raise Invalid, 'Documentation client profile selects an unavailable API version' unless unknown.empty?
 
         @registrations.each do |version, languages|
-          snapshot = languages.dig(:rust, :snapshot)
-          if snapshot && snapshot.fetch('api_version').to_s != version
-            raise Invalid, 'Documentation Rust snapshot API version mismatch'
+          %i[rust typescript].each do |language|
+            snapshot = languages.dig(language, :snapshot)
+            if snapshot && snapshot.fetch('api_version').to_s != version
+              label = language == :rust ? 'Rust' : 'TypeScript'
+              raise Invalid, "Documentation #{label} snapshot API version mismatch"
+            end
           end
         end
       end
@@ -101,7 +105,7 @@ module HaveAPI
 
       def validate_config(language, config)
         unless config.is_a?(Hash) && (config.keys - KEYS.fetch(language)).empty? &&
-               config.all? { |key, value| %i[source module_version crate_version].include?(key) || nonempty_string?(value) }
+               config.all? { |key, value| %i[source module_version crate_version package_version].include?(key) || nonempty_string?(value) }
           raise Invalid, 'Invalid documentation client profile fields'
         end
 
@@ -125,7 +129,11 @@ module HaveAPI
       def load_profile(language, config)
         safely do
           config = validate_config(language, config)
-          language == :go ? load_go(config) : load_rust(config)
+          case language
+          when :go then load_go(config)
+          when :rust then load_rust(config)
+          when :typescript then load_typescript(config)
+          end
         end
       end
 
@@ -211,6 +219,12 @@ module HaveAPI
 
         arguments = { description:, api_version: version, protocol_version: HaveAPI::PROTOCOL_VERSION,
                       mount_path: server.root }
+        if language == :typescript
+          adapter = HaveAPI::TypeScriptClient::Documentation.from_description(
+            **arguments, package_name: config[:name], package_version: config[:version]
+          )
+          return profile(:typescript, config, adapter)
+        end
         if config[:generator_config]
           snapshot = HaveAPI::RustClient::Snapshot.from_description(
             **arguments, source_url: "https://haveapi.invalid#{server.root}v#{version}/", profile: 'server-documentation'
@@ -237,6 +251,35 @@ module HaveAPI
         profile(:rust, config, adapter)
       end
 
+      def load_typescript(config)
+        name = config[:package_name]
+        version = config[:package_version]
+        unless nonempty_string?(name) && name.bytesize <= 214 &&
+               name.match?(%r{\A(?:@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*\z}) &&
+               !%w[node_modules favicon.ico].include?(name) &&
+               (version.nil? || (version.is_a?(String) &&
+                 version.match?(/\A(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?\z/)))
+          raise Invalid, 'Invalid TypeScript documentation client package'
+        end
+
+        require 'haveapi/typescript_client/documentation'
+        unless config.fetch(:generator_version) == HaveAPI::TypeScriptClient::VERSION
+          raise Invalid, 'Documentation TypeScript generator version mismatch'
+        end
+
+        documentation = HaveAPI::TypeScriptClient::Documentation
+        unless documentation.respond_to?(:from_description) && documentation.respond_to?(:from_snapshot)
+          raise Invalid, 'Documentation TypeScript generator has an incompatible profile interface'
+        end
+
+        prepared = { name: name.dup.freeze, version: version&.dup&.freeze }.freeze
+        return prepared unless config.has_key?(:snapshot_path)
+
+        snapshot = JSON.parse(File.read(local_file(config[:snapshot_path])))
+        adapter = documentation.from_snapshot(snapshot:, package_name: name, package_version: version)
+        prepared.merge(snapshot:, profile: profile(:typescript, prepared, adapter)).freeze
+      end
+
       def profile(language, config, adapter)
         unless adapter.respond_to?(:resolve) && adapter.respond_to?(:render)
           raise Invalid, 'Documentation client generator has an incompatible adapter interface'

data/lib/haveapi/documentation_context.rb

@@ -10,26 +10,56 @@ module HaveAPI
       def initialize(version:, host:, base_url:, version_url:, description:,
                      resource_path: [], resource: nil, action_name: nil, action: nil,
                      sample: nil, profile: nil)
-        @version = version.to_s.dup.freeze
-        @host = host.to_s.dup.freeze
-        @base_url = base_url.to_s.dup.freeze
-        @version_url = version_url.to_s.dup.freeze
-        @description = copy(description)
-        @resource_path = copy(resource_path.map(&:to_s))
-        @resource = copy(resource)
-        @action_name = action_name.nil? ? nil : action_name.to_s.dup.freeze
-        @action = copy(action)
-        @sample = copy(sample)
-        @profile = profile
+        @version = normalize(:version, version)
+        @host = normalize(:host, host)
+        @base_url = normalize(:base_url, base_url)
+        @version_url = normalize(:version_url, version_url)
+        @description = normalize(:description, description)
+        @resource_path = normalize(:resource_path, resource_path)
+        @resource = normalize(:resource, resource)
+        @action_name = normalize(:action_name, action_name)
+        @action = normalize(:action, action)
+        @sample = normalize(:sample, sample)
+        @profile = normalize(:profile, profile)
         freeze
       end
 
       def with(**changes)
-        self.class.new(**FIELDS.to_h { |field| [field, public_send(field)] }, **changes)
+        unless instance_of?(Context)
+          return self.class.new(**FIELDS.to_h { |field| [field, public_send(field)] }, **changes)
+        end
+
+        unknown = changes.keys - FIELDS
+        unless unknown.empty?
+          raise ArgumentError, "unknown keyword#{'s' if unknown.length > 1}: #{unknown.map(&:inspect).join(', ')}"
+        end
+
+        # Unchanged fields are already owned snapshots; caller-supplied values
+        # must still cross the same ownership boundary as initial construction.
+        derived = dup
+        changes.each do |field, value|
+          derived.instance_variable_set("@#{field}", normalize(field, value))
+        end
+        derived.freeze
       end
 
       private
 
+      def normalize(field, value)
+        case field
+        when :version, :host, :base_url, :version_url
+          value.to_s.dup.freeze
+        when :resource_path
+          copy(value.map(&:to_s))
+        when :action_name
+          value.nil? ? nil : value.to_s.dup.freeze
+        when :profile
+          value
+        else
+          copy(value)
+        end
+      end
+
       def copy(value)
         case value
         when Hash

data/lib/haveapi/version.rb

@@ -1,4 +1,4 @@
 module HaveAPI
   PROTOCOL_VERSION = '2.0'.freeze
-  VERSION = '0.30.1'.freeze
+  VERSION = '0.31.0'.freeze
 end

data/lib/haveapi/views/version_page.erb

@@ -20,7 +20,7 @@
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/js" target="_blank" rel="noopener">JavaScript and TypeScript (callback and async)</a></li>
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/python" target="_blank" rel="noopener">Python (sync and async)</a></li>
   <% settings.api_server.documentation_client_profiles(@v).each do |language, profile| %>
-    <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/<%= escape_html(language) %>" target="_blank" rel="noopener"><%= language == :go ? 'Go' : 'Rust (async and blocking)' %></a>: <code><%= escape_html(profile.package_name) %></code><% if profile.package_version %> <%= escape_html(profile.package_version) %><% end %></li>
+    <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/<%= escape_html(language) %>" target="_blank" rel="noopener"><%= { go: 'Go', rust: 'Rust (async and blocking)', typescript: 'TypeScript (generated)' }.fetch(language) %></a>: <code><%= escape_html(profile.package_name) %></code><% if profile.package_version %> <%= escape_html(profile.package_version) %><% end %></li>
   <% end %>
   <li><a href="https://github.com/vpsfreecz/haveapi/tree/master/clients/php" target="_blank" rel="noopener">PHP</a></li>
   <li>
@@ -31,7 +31,7 @@
 
 <p>
   These examples target API v<%= escape_html(@v) %>. The framework and dynamic
-  clients share HaveAPI package versions. Generated Go and Rust SDKs use their
+  clients share HaveAPI package versions. Generated Go, Rust and TypeScript SDKs use their
   own package versions. Their configured SDKs are expected to match this API.
 </p>
 

data/spec/client_examples/context_performance_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe HaveAPI::ClientExample::Context, '#with' do
+  let(:sample) { { request: { payload: { 'items' => [0, false, '', nil] } } } }
+  let(:profile) { Object.new.freeze }
+
+  def parent_context(resource_count)
+    action = { input: { parameters: { payload: { type: 'Custom' } } }, examples: [sample] }
+    description = {
+      resources: resource_count.times.to_h do |index|
+        ["resource#{index}", { description: "Resource #{index}", actions: { 'show' => action } }]
+      end
+    }
+    described_class.new(version: '1', host: 'example.test', base_url: 'http://example.test/benchmark/api/',
+                        version_url: 'http://example.test/benchmark/api/v1/', description:,
+                        resource_path: ['resource0'], resource: description[:resources]['resource0'],
+                        action_name: 'show', action:, sample:)
+  end
+
+  def allocated_derivations(parent, changes, count: 40)
+    # Taking the minimum of repeated batches avoids incidental VM bookkeeping
+    # spikes. Expectations and fixture construction stay outside this loop.
+    Array.new(3) do
+      before = GC.stat(:total_allocated_objects)
+      count.times { parent.with(**changes) }
+      GC.stat(:total_allocated_objects) - before
+    end.min
+  end
+
+  it 'shares every unchanged field and owns a different snapshot for a new request' do
+    parent = parent_context(8)
+    other_request = parent_context(8)
+    children = [parent.with(profile:), parent.with(sample:)]
+    fields = %i[version host base_url version_url description resource_path resource action_name action sample profile]
+
+    children.each_with_index do |child, index|
+      changed = index == 0 ? :profile : :sample
+      (fields - [changed]).each do |field|
+        expect(child.public_send(field)).to equal(parent.public_send(field))
+      end
+      expect(child).to be_frozen
+    end
+    expect(other_request.description).to eq(parent.description)
+    expect(other_request.description).not_to equal(parent.description)
+    expect(other_request.description[:resources]).not_to equal(parent.description[:resources])
+    replacement = parent.with(description: parent.description)
+    expect(replacement.description).to eq(parent.description)
+    expect(replacement.description).not_to equal(parent.description)
+  end
+
+  it 'keeps allocations independent of unrelated description size for small changes' do
+    small = parent_context(8)
+    large = parent_context(128)
+    changes = [{ profile: }, { sample: }]
+    [small, large].each do |parent|
+      changes.each { |change| 80.times { parent.with(**change) } }
+    end
+
+    changes.each do |change|
+      small_allocations = allocated_derivations(small, change)
+      large_allocations = allocated_derivations(large, change)
+      # CRuby 3.4 allocates 200/200 objects for profile changes and 560/560 for
+      # samples at these sizes. The original constructor path grows from 12,560
+      # to 151,760. Allow 32 extra objects per derivation for VM bookkeeping;
+      # identity assertions independently forbid whole-description copies.
+      expect(large_allocations).to be <= small_allocations + (40 * 32)
+      [small, large].each do |parent|
+        expect(parent.with(**change).description).to equal(parent.description)
+      end
+    end
+  end
+end

data/spec/client_examples/context_spec.rb

@@ -25,6 +25,212 @@ describe HaveAPI::ClientExample::Context do
     expect(child).to be_frozen
   end
 
+  describe '#with' do
+    let(:fields) do
+      {
+        version: 1, host: 'api.test', base_url: 'https://api.test/mount/',
+        version_url: 'https://api.test/mount/v1/',
+        description: { 'resources' => { 'widget' => { 'label' => 'Widget' } } },
+        resource_path: [:widget, 2], resource: { 'label' => 'Widget' },
+        action_name: :show, action: { 'method' => 'GET' },
+        sample: { 'request' => { 'values' => [0, false, '', nil] } }, profile: Object.new
+      }
+    end
+    let(:parent) { described_class.new(**fields) }
+    let(:replacements) do
+      {
+        version: 2, host: 'other.test', base_url: 'https://other.test/api/',
+        version_url: 'https://other.test/api/v2/',
+        description: { 'resources' => { 'other' => { 'label' => 'Other' } } },
+        resource_path: [:other, 3], resource: { 'label' => 'Other' },
+        action_name: :update, action: { 'method' => 'POST' },
+        sample: { 'request' => { 'values' => [false, 0, nil, ''] } },
+        profile: Object.new
+      }
+    end
+
+    it 'returns a distinct frozen context sharing every unchanged field' do
+      child = parent.with
+
+      expect(child).not_to equal(parent)
+      expect(child).to be_frozen
+      described_class::FIELDS.each do |field|
+        expect(child.public_send(field)).to equal(parent.public_send(field))
+      end
+      expect(child.description['resources']['widget']).to equal(parent.description['resources']['widget'])
+    end
+
+    HaveAPI::ClientExample::Context::FIELDS.each do |field|
+      it "normalizes an explicit #{field} replacement like the constructor and shares other fields" do
+        changed = { field => replacements.fetch(field) }
+        child = parent.with(**changed)
+        constructor = described_class.new(**fields, **changed)
+
+        expect(child).to be_frozen
+        expect(child.public_send(field)).to eq(constructor.public_send(field))
+        (described_class::FIELDS - [field]).each do |unchanged|
+          expect(child.public_send(unchanged)).to equal(parent.public_send(unchanged))
+        end
+        expect(parent.public_send(field)).to eq(described_class.new(**fields).public_send(field))
+      end
+    end
+
+    it 'copies supplied nested containers and strings even when their outer hash is frozen' do
+      key = ['mutable key']
+      source = { key => [{ 'value' => 'safe' }] }.freeze
+      child = parent.with(description: source, resource: source, action: source, sample: source)
+
+      %i[description resource action sample].each do |field|
+        owned = child.public_send(field)
+        expect(owned).not_to equal(source)
+        expect(owned).to be_frozen
+        expect(owned.keys.first).not_to equal(key)
+        expect(owned.keys.first).to be_frozen
+        expect(owned.keys.first.first).to be_frozen
+        expect(owned.values.first).to be_frozen
+        expect(owned.values.first.first).to be_frozen
+        expect(owned.values.first.first.keys.first).to be_frozen
+        expect(owned.values.first.first['value']).to be_frozen
+      end
+      expect(key).not_to be_frozen
+      expect(key.first).not_to be_frozen
+      expect(source.values.first).not_to be_frozen
+      expect(source.values.first.first['value']).not_to be_frozen
+      key.first.replace('changed key')
+      source.values.first.first['value'].replace('changed')
+      %i[description resource action sample].each do |field|
+        expect(child.public_send(field)).to eq(['mutable key'] => [{ 'value' => 'safe' }])
+      end
+    end
+
+    it 'detaches explicitly supplied strings and converts resource path elements without retaining them' do
+      text = +'value'
+      path = [text, :widget, 7]
+      child = parent.with(version: text, host: text, base_url: text, version_url: text,
+                          resource_path: path, action_name: text)
+
+      %i[version host base_url version_url action_name].each do |field|
+        expect(child.public_send(field)).to eq('value')
+        expect(child.public_send(field)).not_to equal(text)
+        expect(child.public_send(field)).to be_frozen
+      end
+      expect(child.resource_path).to eq(%w[value widget 7])
+      expect(child.resource_path).to be_frozen
+      expect(child.resource_path).not_to equal(path)
+      expect(child.resource_path).to all(be_frozen)
+      expect(path).not_to be_frozen
+      expect(text).not_to be_frozen
+      text.replace('changed')
+      path << 'extra'
+      expect(child.version).to eq('value')
+      expect(child.resource_path).to eq(%w[value widget 7])
+    end
+
+    it 'copies explicitly supplied owned values again instead of treating frozen data as trusted' do
+      child = parent.with(description: parent.description, resource_path: parent.resource_path,
+                          sample: parent.sample)
+
+      %i[description resource_path sample].each do |field|
+        expect(child.public_send(field)).to eq(parent.public_send(field))
+        expect(child.public_send(field)).not_to equal(parent.public_send(field))
+      end
+      expect(child.description['resources']).not_to equal(parent.description['resources'])
+      expect(child.sample['request']['values']).not_to equal(parent.sample['request']['values'])
+    end
+
+    it 'keeps parent, sibling and chained derivations detached from their supplied inputs' do
+      data = { request: { name: 'safe' } }
+      child = parent.with(sample: data)
+      sibling = parent.with(sample: data)
+      grandchild = child.with(action_name: :update)
+      fields[:description]['resources']['widget']['label'].replace('changed source')
+      data[:request][:name].replace('changed sample')
+
+      expect(parent.description['resources']['widget']['label']).to eq('Widget')
+      expect(child.description).to equal(parent.description)
+      expect(sibling.description).to equal(parent.description)
+      expect(grandchild.description).to equal(parent.description)
+      expect(parent.sample).to eq('request' => { 'values' => [0, false, '', nil] })
+      expect(child.sample).to eq(request: { name: 'safe' })
+      expect(sibling.sample).to eq(child.sample)
+      expect(sibling.sample).not_to equal(child.sample)
+      expect(grandchild.sample).to equal(child.sample)
+      expect(child.action_name).to eq('show')
+      expect(grandchild.action_name).to eq('update')
+      expect { child.sample[:request][:name].replace('forbidden') }.to raise_error(FrozenError)
+    end
+
+    it 'distinguishes omitted fields from explicit nil replacements' do
+      child = parent.with(description: nil, resource: nil, action_name: nil, action: nil, sample: nil, profile: nil)
+
+      %i[description resource action_name action sample profile].each do |field|
+        expect(child.public_send(field)).to be_nil
+        expect(parent.public_send(field)).not_to be_nil
+      end
+      expect(child.version).to equal(parent.version)
+      expect(parent.with(version: nil, host: nil, base_url: nil, version_url: nil))
+        .to have_attributes(version: '', host: '', base_url: '', version_url: '')
+      expect(context.with.action_name).to be_nil
+    end
+
+    it 'shares arbitrary profiles and non-container leaves without freezing them' do
+      leaf = Object.new
+      profile = fields.fetch(:profile)
+      child = parent.with(description: { custom: leaf }, profile: leaf)
+
+      expect(parent.profile).to equal(profile)
+      expect(parent.with.profile).to equal(profile)
+      expect(profile).not_to be_frozen
+      expect(child.profile).to equal(leaf)
+      expect(child.description[:custom]).to equal(leaf)
+      expect(leaf).not_to be_frozen
+    end
+
+    it 'continues rejecting invalid resource paths' do
+      expect { parent.with(resource_path: nil) }.to raise_error(NoMethodError)
+      expect { described_class.new(**fields, resource_path: nil) }.to raise_error(NoMethodError)
+      expect(parent.resource_path).to eq(%w[widget 2])
+    end
+
+    it 'rejects unknown keywords before normalizing any supplied values' do
+      value = Object.new
+      allow(value).to receive(:to_s).and_call_original
+
+      expect { parent.with(version: value, unknown: true) }.to raise_error(ArgumentError, 'unknown keyword: :unknown')
+      expect { parent.with(unknown: true, other: false) }
+        .to raise_error(ArgumentError, 'unknown keywords: :unknown, :other')
+      expect { parent.with('version' => '2') }.to raise_error(ArgumentError, 'unknown keyword: "version"')
+      expect(value).not_to have_received(:to_s)
+      expect(parent).not_to respond_to(:unknown)
+      expect(parent.version).to eq('1')
+    end
+
+    it 'keeps subclass constructors, extra keywords and constructor effects on every derivation' do
+      subclass = Class.new(described_class) do
+        attr_reader :marker, :initializations
+
+        def initialize(marker: :default, initializations: 0, **fields)
+          @marker = marker
+          @initializations = initializations + 1
+          super(**fields)
+        end
+      end
+      original = subclass.new(**fields, marker: :original)
+      child = original.with(marker: :child, initializations: original.initializations)
+      defaulted = original.with
+
+      expect(child).to be_a(subclass)
+      expect(child).to be_frozen
+      expect(child.marker).to eq(:child)
+      expect(child.initializations).to eq(2)
+      expect(defaulted.marker).to eq(:default)
+      expect(original.marker).to eq(:original)
+      expect(original.initializations).to eq(1)
+      expect(child.description).to eq(original.description)
+      expect(child.description).not_to equal(original.description)
+    end
+  end
+
   it 'preserves legacy initialization constructors and wraps plain source' do
     renderer = Class.new(HaveAPI::ClientExample) do
       def initialize(host, base_url, version)

data/spec/client_examples/profile_mount_spec.rb

@@ -139,6 +139,20 @@ describe HaveAPI::Server, '#mount' do
     )
   end
 
+  def register_typescript
+    generator = Module.new
+    generator.const_set(:VERSION, HaveAPI::VERSION)
+    generator.const_set(:Documentation, documentation)
+    stub_const('HaveAPI::TypeScriptClient', generator)
+    allow(registry).to receive(:require).with('haveapi/typescript_client/documentation').and_return(true)
+    allow(documentation).to receive(:from_description) do |description:, **|
+      descriptions << description
+      adapter
+    end
+    allow(documentation).to receive(:from_snapshot).and_return(adapter)
+    server.documentation_clients(1, typescript: { package_name: '@example/widget-client' })
+  end
+
   it 'captures the complete selected version after auth, action-state and post-mount routes exist' do
     register
     server.action_state = Object.new
@@ -212,4 +226,35 @@ describe HaveAPI::Server, '#mount' do
     expect(server.app).to be_nil
     expect(server.documentation_client_profiles(1)).to be_empty
   end
+
+  it 'mounts a generated TypeScript panel beside dynamic tabs using only authorized request samples' do
+    register_typescript
+    server.mount('/mounted/api/')
+    expect(descriptions.size).to eq(1)
+    private_schema = descriptions.first
+    expect(private_schema).to be_frozen
+    expect(JSON.generate(private_schema)).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE')
+    expect(private_schema.dig('resources', 'widget', 'actions')).to have_key('secret')
+    expect(request_as('admin', 'en').body).to include('PRIVATE_SAMPLE')
+    contexts.clear
+    response = request_as('member', 'en')
+    expect(response.status).to eq(200)
+    expect(response.body).to include('TypeScript (generated)', 'init-typescript-generated', 'init-typescript-callback',
+                                     'init-typescript-async', 'example-widget-show-0-typescript-generated', '@example/widget-client')
+    expect(response.body).not_to include('PRIVATE_DEFAULT', 'PRIVATE_SAMPLE', 'PRIVATE_RESPONSE', 'admin_only')
+    selected = contexts.find { |context| context.action_name == 'show' }
+    expect(selected.version_url).to eq('http://example.org/mounted/api/v1/')
+    expect(selected.action.dig(:input, :parameters).keys).to eq([:visible])
+    expect(selected.sample[:request]).to eq(visible: 'public sample')
+    expect(documentation).to have_received(:from_description).once
+  end
+
+  it 'aborts the whole mount when the generated TypeScript adapter rejects the full declaration' do
+    register_typescript
+    allow(documentation).to receive(:from_description).and_raise('PRIVATE_TYPESCRIPT_DIAGNOSTIC')
+    expect { server.mount('/') }.to raise_error(HaveAPI::ClientExample::Profiles::Invalid,
+                                                'Configured documentation client schema or configuration is invalid')
+    expect(server.app).to be_nil
+    expect(server.documentation_client_profiles(1)).to be_empty
+  end
 end

data/spec/client_examples/ts_generated_client_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+class TypeScriptDocumentationAdapterFixture
+  def render(kind:, context:, mode:, auth_method: nil, auth_description: nil); end
+end
+
+describe HaveAPI::ClientExamples::TsGeneratedClient do
+  let(:adapter) { instance_spy(TypeScriptDocumentationAdapterFixture) }
+  let(:profile) { Struct.new(:language, :adapter).new(:typescript, adapter).freeze }
+  let(:context) do
+    HaveAPI::ClientExample::Context.new(
+      version: '1.0', host: 'example.test', base_url: 'https://example.test/mount/',
+      version_url: 'https://example.test/mount/v1.0/', description: {},
+      resource_path: ['widget'], action_name: 'update', action: {}, sample: { request: {} }, profile:
+    )
+  end
+
+  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.code).to eq(:typescript)
+    expect(HaveAPI::ClientExamples::TsClient.id).to eq('typescript-callback')
+    expect(HaveAPI::ClientExamples::TsAsyncClient.id).to eq('typescript-async')
+  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)
+    expect(described_class.available?(context.with(profile: Struct.new(:language).new(:rust)))).to be(false)
+    expect(described_class.available?(context)).to be(true)
+  end
+
+  it 'delegates the immutable authorized context and exact authentication metadata' do
+    result = { status: :code, code: 'generated TypeScript' }.freeze
+    allow(adapter).to receive(:render).and_return(result)
+    expect(described_class.render(:init, context:)).to eq(result)
+    expect(described_class.render(:auth, context:, auth_method: :token, auth_description: { http_header: 'X-Token' })).to eq(result)
+    expect(adapter).to have_received(:render).with(kind: :init, context:, mode: :async)
+    expect(adapter).to have_received(:render).with(kind: :auth, context:, mode: :async, auth_method: :token,
+                                                   auth_description: { http_header: 'X-Token' })
+  end
+
+  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
+    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)
+    expect(adapter).to have_received(:render).with(kind: :example, mode: :async, context: have_attributes(sample: sample))
+    expect(renderer.init).to eq(result)
+    expect(described_class.new('example.test', 'https://example.test/', '1.0').init).to include(status: :limitation)
+  end
+end