haveapi-typescript-client 0.32.1 → 0.32.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 671560335eaec7e5fba76ee4ba21e89116ae9e073d0a91b2828a2d0f951b1bab
-  data.tar.gz: a7cb5a9cfdef8cc1b3b78e70200548d4e16ec77181e66400044f359d3fbbdfd6
+  metadata.gz: 93c27159dde8cece29caa28dff63ff8cf2c79d7e637bc9417fe8e7c9619365a3
+  data.tar.gz: 4bc3f5b3466df58c7328fd5edd41fab0aaf333990f4b2b9f4d35e7645f7f79be
 SHA512:
-  metadata.gz: c489af5479d2dec585303ceb2a932e45bb152901666e1cdb97b9ea18bd7caf2ede1cf00a7fcf9b3ddfe9c170cf6b1843695283dff387e165736f6a10c38ba3b2
-  data.tar.gz: aaea1e28c31789fe8ec4c17ca1ff640d7cd41a337eca458cb52cf66aac2716635a1dbc1d10c7dc7c38edadd69a169ce17e61b765861c1a201fc2a412c4ba2069
+  metadata.gz: 44925fd9911f1592657f2d3462ca4ea771deb62e9a6fc53669b04c8047eb1a0ae44c33a94b22b32ea001b8fdaeca24d90fa2ccd6014999624a98b7f132deb281
+  data.tar.gz: a0ffc483c8e72a45e4a9f8a04a20145bf11475b2379574cfffe86c53266539f82fbd676b522a74b7b907f5d0de8b76fb9f2d6bd0b0ee3f2541e603cc27887d7f

data/README.md

@@ -36,7 +36,7 @@ checkout revision and resolved dependency inputs. Generation reads local files
 using the prepared dependencies and runs without contacting the API.
 
 Applications need a TypeScript compiler and the `haveapi-client` JavaScript
-runtime. The supported runtime version is exactly `0.30.2`.
+runtime. The supported runtime version is exactly `0.32.0`.
 
 Both generation and `generate --check` require **Prettier 3.9.10** and Node.
 The repository's default Nix shell supplies them. For an installed Ruby gem,
@@ -123,7 +123,7 @@ and a TypeScript compiler:
 
 ```sh
 cd /path/to/widget-client
-npm install --save-exact haveapi-client@0.30.2
+npm install --save-exact haveapi-client@0.32.0
 npm install --save-dev typescript
 ```
 
@@ -156,6 +156,57 @@ Raw request results cannot be passed to
 `AsyncClient.waitForCompletion`; see the
 [JavaScript runtime guide](../js/README.md#advanced-usage-and-reference).
 
+Each action returns `ActionResult<Output, GlobalOutput>`. Its `meta` has the
+declared global output fields, preserving optional/null values, and accepts
+additional unknown server fields. The complete envelope and HTTP status remain
+available. This typing does not validate payload or metadata fields at runtime.
+
+Read live descriptions through the same executor:
+
+```ts
+const description = await api.describe({signal: new AbortController().signal});
+const capability = await api.widget.update.describe({path: {widget_id: 1}});
+const required = capability.data.input?.parameters?.['name']?.required;
+```
+
+`api.describe` sends OPTIONS to the selected version root. An action's `describe`
+uses its saved help route and encoded IDs, with the recorded HTTP method selector;
+older snapshots without help use the validated action route and method.
+Explicit help without the action's method selector is rejected during generation.
+Headers, signal and timeout can be supplied, but arbitrary HTTP routes and
+mutation input cannot. Aliases share the same callable action and `describe`
+function. A root resource named `describe` is rejected as a name collision
+during generation.
+The exported protocol description types are conservative and extensible. Fields
+can be absent or null, and consumers must narrow the parts they use. The
+executor retains responsibility for envelope errors. Static generated client
+action presence does not establish authorization or field availability; live
+descriptions can hide actions/fields or fail. The generator does not cache
+descriptions or infer permissions from them.
+
+Generated local input, JSON and path checks throw `ClientInputError`, a
+`TypeError` subclass with `code: 'HAVEAPI_CLIENT_INPUT_ERROR'` and
+`phase: 'pre-dispatch'`. This error means the executor was never called, so no
+mutation was sent. Errors from the executor pass through unchanged; an ordinary
+transport `TypeError` must not be treated as a proven local failure. Error
+objects do not retain input values.
+
+When the deployed API uses a different metadata namespace, bind one override:
+
+```ts
+const api = createClient({execute: spec => runtime.request(spec), metaNamespace: 'meta'});
+```
+
+The default is the saved schema's namespace. Generated input keys remain those
+in the schema (for example `params._meta`); the generator maps declared object
+metadata to the effective wire key and sets `RequestSpec.metaNamespace` for
+ordinary and description requests. Global metadata still uses `options.meta`.
+For declared object-list output metadata, `data` exposes the canonical schema
+key. The projection preserves Custom/nested values and the original envelope;
+it never walks arbitrary payloads. Invalid/reserved namespace overrides or
+collisions with declared input/output fields fail before dispatch. Bind a new
+client when the effective namespace changes.
+
 ## Schemas and types
 
 Input is a format 1 snapshot with `api_version`, `protocol_version` (major 2),
@@ -189,6 +240,7 @@ src/generated/
   index.ts
   api.ts
   runtime.ts
+  descriptions.ts
   types.ts
   resources/
     widget/

data/docs/documentation.md

@@ -2,7 +2,7 @@
 
 The Ruby server can show examples for a generated TypeScript SDK alongside its
 dynamic TypeScript clients. The generated examples use the SDK's public
-`createClient` factory and `haveapi-client` version `0.30.2` for requests and
+`createClient` factory and `haveapi-client` version `0.32.0` for requests and
 authentication. The server prepares the SDK model at mount time and renders
 examples when users view the documentation.
 
@@ -103,7 +103,7 @@ TypeScript 6, NodeNext/ES2022, `exactOptionalPropertyTypes`,
 `noUncheckedIndexedAccess` and `verbatimModuleSyntax`. They cover aliases, nested
 paths, filtered fields, stale contracts, supported authentication and errors.
 
-Run the wire harness with a prepared published `haveapi-client@0.30.2`
+Run the wire harness with a prepared published `haveapi-client@0.32.0`
 installation:
 
 ```sh

data/haveapi-typescript-client.gemspec

@@ -14,5 +14,5 @@ Gem::Specification.new do |spec|
   spec.bindir = 'bin'
   spec.executables = ['haveapi-typescript-client']
   spec.require_paths = ['lib']
-  spec.add_dependency 'haveapi-client', '~> 0.32.1'
+  spec.add_dependency 'haveapi-client', '~> 0.32.2'
 end

data/lib/haveapi/typescript_client/documentation.rb

@@ -56,7 +56,7 @@ module HaveAPI::TypeScriptClient
       { status: :code, code: source.freeze }.freeze
     rescue Unsupported, JSON::GeneratorError, EncodingError
       # Never name fields or actions from the private API client in public diagnostics.
-      { status: :limitation, reason: 'This sample is unavailable or incompatible with the configured TypeScript API client.'.freeze }.freeze
+      { status: :limitation, reason: documentation_message('generated.typescript.unavailable', context:, default: 'This sample is unavailable or incompatible with the configured TypeScript API client.').freeze }.freeze
     end
 
     def detail_levels_for(kind:, context:, result:, mode:, auth_method: nil, auth_description: nil)
@@ -67,6 +67,26 @@ module HaveAPI::TypeScriptClient
 
     private
 
+    def documentation_message(key, context:, default:, **values)
+      if context.respond_to?(:documentation_message)
+        context.documentation_message(key, default:, **values)
+      else
+        values.empty? ? default : format(default, values)
+      end
+    end
+
+    def example_comment(key, context:, default:, **values)
+      if context.respond_to?(:example_comment)
+        context.example_comment(key, default:, **values)
+      else
+        values.empty? ? default : format(default, values)
+      end
+    end
+
+    def comment_lines(text, prefix)
+      text.gsub(/\r\n?/, "\n").split("\n", -1).map { |line| "#{prefix}#{line}" }.join("\n")
+    end
+
     def unsupported!
       raise Unsupported
     end
@@ -125,7 +145,7 @@ module HaveAPI::TypeScriptClient
 
     def program(context, body, auth = [], errors: false)
       version_url = version_url(context)
-      dependencies = "// Configured API client: #{@package_name}#{"@#{@package_version}" if @package_version}."
+      dependencies = comment_lines(example_comment('typescript_package', default: 'Configured API client: %{package}.', context:, package: "#{@package_name}#{"@#{@package_version}" if @package_version}"), '// ')
       runtime_imports = errors ? 'AsyncClient, AsyncError' : 'AsyncClient'
       lines = [dependencies, "import { #{runtime_imports} } from #{literal('haveapi-client')};", "import { createClient } from #{literal(@package_name)};"]
       lines += ['', 'async function main(): Promise<void> {']
@@ -327,14 +347,14 @@ module HaveAPI::TypeScriptClient
         body << 'void [result.data, result.meta, result.envelope, result.httpStatus];' if context.detail == :thorough
         body.concat(output_lines(action, response, thorough: context.detail == :thorough))
       end
-      body << '// Request success does not establish completion of a server-side operation.' if action.fetch(:blocking)
+      body << comment_lines(example_comment('typescript_completion', default: 'Request success does not establish completion of a server-side operation.', context:), '// ') if action.fetch(:blocking)
       auth = action_authentication(action, context)
       if context.detail == :thorough
         return program(context, body, auth, errors: true)
       end
 
       imports = failure ? ["import { AsyncError } from #{literal('haveapi-client')};", ''] : []
-      (imports + ['// Requires an initialized api and an async context.'] + body + ['']).join("\n")
+      (imports + [comment_lines(example_comment('typescript_async_context', default: 'Requires an initialized api and an async context.', context:), '// ')] + body + ['']).join("\n")
     end
 
     def output_lines(action, response, thorough:)

data/lib/haveapi/typescript_client/emitter.rb

@@ -5,7 +5,7 @@ module HaveAPI::TypeScriptClient
   # Templates are source inputs loaded once, outside the pure emission seam.
   class Emitter
     TEMPLATE_ROOT = File.expand_path('../../../template', __dir__).freeze
-    TEMPLATES = %w[action api index resource runtime types].to_h do |name|
+    TEMPLATES = %w[action api descriptions index resource runtime types].to_h do |name|
       [name, File.read(File.join(TEMPLATE_ROOT, "#{name}.ts.erb"), encoding: 'UTF-8').freeze]
     end.freeze
     IO_SUFFIXES = {
@@ -35,7 +35,7 @@ module HaveAPI::TypeScriptClient
     private
 
     def file_plan
-      plan = %w[api index runtime types].map { |name| { path: "#{name}.ts", template: name, origin: "generated root #{name}" } }
+      plan = %w[api descriptions index runtime types].map { |name| { path: "#{name}.ts", template: name, origin: "generated root #{name}" } }
       walk = lambda do |items, parent|
         items.each do |resource|
           directory = "#{parent}resources/#{resource.fetch(:accessor_name)}/"
@@ -89,7 +89,7 @@ module HaveAPI::TypeScriptClient
         [@resource_paths.fetch(resource.fetch(:schema_path)), ["#{resource.fetch(:export_name)}Resource"]]
       end
       action_exports = @ir.fetch(:actions).map do |action|
-        names = [*IO_SUFFIXES.values, 'Path', 'Options'].map { |suffix| action_type(action, suffix) }
+        names = [*IO_SUFFIXES.values, 'Path', 'Options', 'DescribeOptions', 'Action'].map { |suffix| action_type(action, suffix) }
         [@action_paths.fetch(action.fetch(:schema_path)), names]
       end
       (resource_exports + action_exports).sort.map do |path, names|
@@ -178,7 +178,8 @@ module HaveAPI::TypeScriptClient
         elsif key == :output && io && io.fetch(:layout) == 'object_list' && action[:object_output]
           lines << "  #{literal(@ir.fetch(:metadata_namespace))}?: #{action_type(action, 'ObjectOutput')} | null;"
         end
-        shape = lines.empty? ? 'Record<string, never>' : "{\n#{lines.join("\n")}\n}"
+        empty = key == :global_output ? 'Record<never, never>' : 'Record<string, never>'
+        shape = lines.empty? ? empty : "{\n#{lines.join("\n")}\n}"
         shape = "Array<#{shape}>" if io && io.fetch(:layout).end_with?('_list')
         shape = 'unknown' if key == :output && io.nil?
         declarations << "export type #{action_type(action, suffix)} = #{shape};"
@@ -198,6 +199,13 @@ module HaveAPI::TypeScriptClient
       options << "  signal?: RequestSpec['signal'];"
       options << "  timeoutMs?: RequestSpec['timeoutMs'];"
       declarations << "export interface #{action_type(action, 'Options')} {\n#{options.join("\n")}\n}"
+      declarations << "export interface #{action_type(action, 'DescribeOptions')} extends DescribeOptions {\n  path#{'?' if paths.empty?}: #{paths.empty? ? 'undefined' : action_type(action, 'Path')};\n}"
+      declarations << <<~TS.chomp
+        export interface #{action_type(action, 'Action')} {
+          (options#{'?' unless options_required?(action)}: #{action_type(action, 'Options')}): Promise<ActionResult<#{action_type(action, 'Output')}, #{action_type(action, 'GlobalOutput')}>>;
+          describe(options#{'?' if paths.empty?}: #{action_type(action, 'DescribeOptions')}): Promise<ActionResult<ActionDescription>>;
+        }
+      TS
       declarations.join("\n\n")
     end
 
@@ -211,7 +219,7 @@ module HaveAPI::TypeScriptClient
       end
       resource.fetch(:actions).each do |action|
         action_names(action).each do |name|
-          members << "  readonly #{literal(name)}: (options#{'?' unless options_required?(action)}: #{action_type(action, 'Options')}) => Promise<RequestResult<#{action_type(action, 'Output')}>>;"
+          members << "  readonly #{literal(name)}: #{action_type(action, 'Action')};"
         end
       end
       "export interface #{resource.fetch(:export_name)}Resource {\n#{members.join("\n")}\n}"
@@ -226,13 +234,16 @@ module HaveAPI::TypeScriptClient
     end
 
     def action_definition(action)
+      object_output = action[:object_output] && action[:output]&.fetch(:layout) == 'object_list'
       {
-        method: action.fetch(:method), path: action.fetch(:path_template),
+        method: action.fetch(:method), path: action.fetch(:path_template), helpPath: action.fetch(:help_path),
         placeholders: action.fetch(:placeholders).map { |name| [name, Naming.identifier(name)] },
         inputNamespace: (action[:input] && action[:input][:namespace]) || nil,
         outputNamespace: (action[:output] && action[:output][:namespace]) || nil,
         metaNamespace: @ir.fetch(:metadata_namespace), input: field_definitions(action[:input]),
-        globalInput: field_definitions(action[:global_input]), objectInput: field_definitions(action[:object_input])
+        globalInput: field_definitions(action[:global_input]), objectInput: field_definitions(action[:object_input]),
+        outputNames: object_output ? action[:output].fetch(:parameters).map { |field| field.fetch(:wire_name) } : nil,
+        objectOutput: object_output
       }
     end
   end

data/lib/haveapi/typescript_client/ir.rb

@@ -44,7 +44,7 @@ module HaveAPI::TypeScriptClient
     def walk(map, parents, authentication: false)
       fail_at('resources must be an object', parents) unless map.is_a?(Hash)
 
-      scope = Naming::Scope.new
+      scope = Naming::Scope.new(parents.empty? && !authentication ? Naming::RESERVED + ['describe'] : Naming::RESERVED)
       map.sort.map do |name, desc|
         path = parents + [name]
         fail_at('resource must be an object', path) unless desc.is_a?(Hash)
@@ -71,7 +71,7 @@ module HaveAPI::TypeScriptClient
       fail_at('action must be an object', path) unless desc.is_a?(Hash)
       accessor = scope.add(Naming.identifier(name), path.join('/'))
       export = Naming.export(path)
-      %w[Path Input Output GlobalInput GlobalOutput ObjectInput ObjectOutput Options].each do |suffix|
+      %w[Path Input Output GlobalInput GlobalOutput ObjectInput ObjectOutput Options DescribeOptions Action].each do |suffix|
         @exports.add("#{export}#{suffix}", "#{path.join('/')} (#{suffix})")
       end
       aliases = desc.fetch('aliases', [])
@@ -88,7 +88,8 @@ module HaveAPI::TypeScriptClient
       placeholders.each { |item| placeholder_scope.add(Naming.identifier(item), (path + ['path', item]).join('/')) }
       action = {
         schema_path: path, export_name: export, accessor_name: accessor, aliases:, method: desc['method'],
-        path_template: route, placeholders:, auth: desc.fetch('auth', true) != false, blocking: desc['blocking'] == true,
+        path_template: route, help_path: help_route(desc, route, path, placeholders, authentication:),
+        placeholders:, auth: desc.fetch('auth', true) != false, blocking: desc['blocking'] == true,
         input: io(desc['input'], path + ['input'], input: true), output: io(desc['output'], path + ['output'])
       }
       metadata = desc['meta'] || {}
@@ -186,6 +187,22 @@ module HaveAPI::TypeScriptClient
       "/#{relative}"
     end
 
+    def help_route(desc, action_route, path, placeholders, authentication:)
+      return "#{action_route}?method=#{desc['method']}" unless desc.has_key?('help')
+
+      help = desc['help']
+      fail_at('invalid action help route', path) unless help.is_a?(String)
+      help_path, query = help.split('?', -1)
+      unless query == "method=#{desc['method']}"
+        fail_at('action help method differs from action method', path)
+      end
+      relative = route(help_path, path + ['help'], authentication:)
+      unless relative.scan(/\{([^}]+)\}/).flatten.uniq.sort == placeholders.sort
+        fail_at('action help placeholders differ from action path', path)
+      end
+      "#{relative}?#{query}"
+    end
+
     def freeze_data(value)
       case value
       when Hash

data/lib/haveapi/typescript_client/naming.rb

@@ -1,7 +1,11 @@
 module HaveAPI::TypeScriptClient
   module Naming
     RESERVED = %w[then constructor prototype __proto__].freeze
-    EXPORT_RESERVED = %w[createClient RequestExecutor ClientOptions JsonValue API_VERSION SCHEMA_SHA256 RequestOptions executeAction].freeze
+    EXPORT_RESERVED = %w[
+      createClient RequestExecutor ClientOptions JsonValue API_VERSION SCHEMA_SHA256 RequestOptions executeAction
+      ActionResult ClientInputError ApiDescription ActionDescription ResourceDescription ParameterDescription
+      IoDescription MetadataDescription AuthenticationDescription DescribeOptions
+    ].freeze
 
     def self.identifier(name)
       raise Error, 'schema name must be a nonempty string' unless name.is_a?(String) && !name.empty?

data/lib/haveapi/typescript_client/version.rb

@@ -1,5 +1,5 @@
 module HaveAPI
   module TypeScriptClient
-    VERSION = '0.32.1'.freeze
+    VERSION = '0.32.2'.freeze
   end
 end

data/template/action.ts.erb

@@ -1,13 +1,18 @@
 // Generated by HaveAPI. Regenerate from the recorded schema; do not edit.
-import type {RequestSpec, RequestResult} from <%= literal(@runtime_import) %>;
-import {executeAction} from <%= literal(relative_import('runtime.ts')) %>;
-import type {JsonValue, RequestExecutor} from <%= literal(relative_import('runtime.ts')) %>;
+import type {RequestSpec} from <%= literal(@runtime_import) %>;
+import {executeAction, describeAction, metadataNamespace} from <%= literal(relative_import('runtime.ts')) %>;
+import type {ActionDescription} from <%= literal(relative_import('descriptions.ts')) %>;
+import type {ActionResult, DescribeOptions, JsonValue, RequestExecutor} from <%= literal(relative_import('runtime.ts')) %>;
 
 <%= action_declarations(@record) %>
 
 const descriptor = <%= literal(action_definition(@record)) %> as const;
 
 /** Internal operation binding; public callers use createClient. */
-export function createAction(execute: RequestExecutor): (options<%= '?' unless options_required?(@record) %>: <%= action_type(@record, 'Options') %>) => Promise<RequestResult<<%= action_type(@record, 'Output') %>>> {
-  return (options: <%= action_type(@record, 'Options') %><%= ' = {}' unless options_required?(@record) %>) => executeAction<<%= action_type(@record, 'Output') %>>(execute, descriptor, options);
+export function createAction(execute: RequestExecutor, metaNamespace?: string): <%= action_type(@record, 'Action') %> {
+  const namespace = metadataNamespace(metaNamespace, descriptor);
+  const invoke = (options: <%= action_type(@record, 'Options') %><%= ' = {}' unless options_required?(@record) %>) => executeAction<<%= action_type(@record, 'Output') %>, <%= action_type(@record, 'GlobalOutput') %>>(execute, descriptor, options, namespace);
+  return Object.assign(invoke, {
+    describe: (options: <%= action_type(@record, 'DescribeOptions') %><%= ' = {}' if @record.fetch(:placeholders).empty? %>) => describeAction(execute, descriptor, options, namespace),
+  });
 }

data/template/api.ts.erb

@@ -1,5 +1,7 @@
 // Generated by HaveAPI. Regenerate from the recorded schema; do not edit.
-import type {ClientOptions} from './runtime.js';
+import {describeApi, metadataNamespace} from './runtime.js';
+import type {ActionResult, ClientOptions, DescribeOptions} from './runtime.js';
+import type {ApiDescription} from './descriptions.js';
 <% @ir.fetch(:resources).each_with_index do |resource, index| -%>
 import {createResource as resource<%= index %>} from <%= literal(relative_import(@resource_paths.fetch(resource.fetch(:schema_path)))) %>;
 import type {<%= resource.fetch(:export_name) %>Resource} from <%= literal(relative_import(@resource_paths.fetch(resource.fetch(:schema_path)))) %>;
@@ -15,14 +17,17 @@ export const SCHEMA_SHA256 = <%= literal(@ir.fetch(:schema_sha256)) %>;
  * Generated output types do not validate response application fields at runtime.
  * Authentication and completion remain with the consumer's HaveAPI runtime.
  */
-export function createClient({execute}: ClientOptions): {
+export function createClient({execute, metaNamespace}: ClientOptions): {
+  readonly describe: (options?: DescribeOptions) => Promise<ActionResult<ApiDescription>>;
 <% @ir.fetch(:resources).each do |resource| -%>
   readonly <%= literal(resource.fetch(:accessor_name)) %>: <%= resource.fetch(:export_name) %>Resource;
 <% end -%>
 } {
+  const namespace = metadataNamespace(metaNamespace);
   return {
+    describe: (options: DescribeOptions = {}) => describeApi(execute, options, namespace),
 <% @ir.fetch(:resources).each_with_index do |resource, index| -%>
-    <%= literal(resource.fetch(:accessor_name)) %>: resource<%= index %>(execute),
+    <%= literal(resource.fetch(:accessor_name)) %>: resource<%= index %>(execute, namespace),
 <% end -%>
   };
 }

data/template/descriptions.ts.erb

@@ -0,0 +1,64 @@
+// Generated by HaveAPI. Regenerate from the recorded schema; do not edit.
+/** Live protocol-2 descriptions are permission-filtered, extensible wire data.
+ * Their application fields are not validated by the generated client. */
+export interface ParameterDescription {
+  type?: string | null;
+  required?: boolean | null;
+  nullable?: boolean | null;
+  protected?: boolean | null;
+  label?: string | null;
+  description?: string | null;
+  default?: unknown;
+  validators?: Record<string, unknown> | null;
+  resource?: string[] | null;
+  value_id?: string | null;
+  value_label?: string | null;
+  value?: {path?: string; method?: string; help?: string; [key: string]: unknown} | null;
+  choices?: Record<string, unknown> | null;
+  [key: string]: unknown;
+}
+export interface IoDescription {
+  layout?: 'object' | 'object_list' | 'hash' | 'hash_list' | null;
+  namespace?: string | false | null;
+  parameters?: Record<string, ParameterDescription> | null;
+  [key: string]: unknown;
+}
+export interface MetadataDescription {
+  input?: IoDescription | null;
+  output?: IoDescription | null;
+  [key: string]: unknown;
+}
+export interface ActionDescription {
+  auth?: boolean | null;
+  blocking?: boolean | null;
+  aliases?: string[] | null;
+  description?: string | null;
+  method?: string | null;
+  path?: string | null;
+  help?: string | null;
+  input?: IoDescription | null;
+  output?: IoDescription | null;
+  meta?: {global?: MetadataDescription | null; object?: MetadataDescription | null; [key: string]: unknown} | null;
+  examples?: unknown[] | null;
+  [key: string]: unknown;
+}
+export interface ResourceDescription {
+  description?: string | null;
+  actions?: Record<string, ActionDescription> | null;
+  resources?: Record<string, ResourceDescription> | null;
+  [key: string]: unknown;
+}
+export interface AuthenticationDescription {
+  http_header?: string | null;
+  query_parameter?: string | null;
+  revoke_url?: string | null;
+  resources?: Record<string, ResourceDescription> | null;
+  [key: string]: unknown;
+}
+export interface ApiDescription {
+  authentication?: Record<string, AuthenticationDescription> | null;
+  resources?: Record<string, ResourceDescription> | null;
+  meta?: {namespace?: string | null; [key: string]: unknown} | null;
+  help?: string | null;
+  [key: string]: unknown;
+}

data/template/index.ts.erb

@@ -1,3 +1,5 @@
 // Generated by HaveAPI. Regenerate from the recorded schema; do not edit.
 export * from './api.js';
-export type {ClientOptions, JsonValue, RequestExecutor} from './runtime.js';
+export {ClientInputError} from './runtime.js';
+export type {ActionResult, ClientOptions, DescribeOptions, JsonValue, RequestExecutor} from './runtime.js';
+export type * from './descriptions.js';

data/template/resource.ts.erb

@@ -1,5 +1,4 @@
 // Generated by HaveAPI. Regenerate from the recorded schema; do not edit.
-import type {RequestResult} from <%= literal(@runtime_import) %>;
 import type {RequestExecutor} from <%= literal(relative_import('runtime.ts')) %>;
 <% @record.fetch(:children).each_with_index do |child, index| -%>
 import {createResource as child<%= index %>} from <%= literal(relative_import(@resource_paths.fetch(child.fetch(:schema_path)))) %>;
@@ -7,19 +6,19 @@ import type {<%= child.fetch(:export_name) %>Resource} from <%= literal(relative
 <% end -%>
 <% @record.fetch(:actions).each_with_index do |action, index| -%>
 import {createAction as bind<%= index %>} from <%= literal(relative_import(@action_paths.fetch(action.fetch(:schema_path)))) %>;
-import type {<%= action_type(action, 'Options') %>, <%= action_type(action, 'Output') %>} from <%= literal(relative_import(@action_paths.fetch(action.fetch(:schema_path)))) %>;
+import type {<%= action_type(action, 'Action') %>} from <%= literal(relative_import(@action_paths.fetch(action.fetch(:schema_path)))) %>;
 <% end -%>
 
 <%= resource_declaration(@record) %>
 
 /** Internal resource composition; public callers use createClient. */
-export function createResource(execute: RequestExecutor): <%= @record.fetch(:export_name) %>Resource {
+export function createResource(execute: RequestExecutor, metaNamespace?: string): <%= @record.fetch(:export_name) %>Resource {
 <% @record.fetch(:actions).each_with_index do |_action, index| -%>
-  const action<%= index %> = bind<%= index %>(execute);
+  const action<%= index %> = bind<%= index %>(execute, metaNamespace);
 <% end -%>
   return {
 <% @record.fetch(:children).each_with_index do |child, index| -%>
-    <%= literal(child.fetch(:accessor_name)) %>: child<%= index %>(execute),
+    <%= literal(child.fetch(:accessor_name)) %>: child<%= index %>(execute, metaNamespace),
 <% end -%>
 <% @record.fetch(:actions).each_with_index do |action, index| -%>
 <% action_names(action).each do |name| -%>

data/template/runtime.ts.erb

@@ -1,9 +1,28 @@
 // Generated by HaveAPI. Regenerate from the recorded schema; do not edit.
 import type {RequestSpec, RequestResult} from <%= literal(@runtime_import) %>;
+import type {ActionDescription, ApiDescription} from './descriptions.js';
 
 export type JsonValue = null | boolean | number | string | JsonValue[] | {[key: string]: JsonValue};
 export type RequestExecutor = (spec: RequestSpec) => Promise<RequestResult<unknown>>;
-export interface ClientOptions {execute: RequestExecutor}
+export interface ClientOptions {execute: RequestExecutor; metaNamespace?: string}
+/** Metadata fields retain the action contract and unknown server extensions. */
+export type ActionResult<TData, TMeta = Record<string, unknown>> = Omit<RequestResult<TData>, 'meta'> & {
+  meta: TMeta & Record<string, unknown>;
+};
+export interface DescribeOptions {
+  headers?: RequestSpec['headers'];
+  signal?: RequestSpec['signal'];
+  timeoutMs?: RequestSpec['timeoutMs'];
+}
+/** Validation failed locally before the executor was called; no write was sent. */
+export class ClientInputError extends TypeError {
+  readonly code = 'HAVEAPI_CLIENT_INPUT_ERROR' as const;
+  readonly phase = 'pre-dispatch' as const;
+  constructor(message: string) {
+    super(message);
+    this.name = 'ClientInputError';
+  }
+}
 
 interface Field {
   wire_name: string;
@@ -15,6 +34,7 @@ interface Field {
 interface Action {
   method: string;
   path: string;
+  helpPath: string;
   placeholders: readonly (readonly [string, string])[];
   inputNamespace: string | null;
   outputNamespace: string | null;
@@ -22,6 +42,8 @@ interface Action {
   input: readonly Field[] | null;
   globalInput: readonly Field[] | null;
   objectInput: readonly Field[] | null;
+  outputNames: readonly string[] | null;
+  objectOutput: boolean | null;
 }
 interface Options {
   path?: Record<string, string | number> | undefined;
@@ -39,7 +61,22 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function fail(message: string): never {
-  throw new TypeError(message);
+  throw new ClientInputError(message);
+}
+/** Bind a single wire namespace; schema-named input/output metadata stays canonical. */
+export function metadataNamespace(override?: string, action?: Action): string {
+  const namespace = override === undefined ? <%= literal(@ir.fetch(:metadata_namespace)) %> : override;
+  if (typeof namespace !== 'string' || namespace.length === 0 || ['then', 'constructor', 'prototype', '__proto__'].includes(namespace))
+    fail('Invalid metadata namespace');
+  if (action && namespace !== action.metaNamespace) {
+    if (namespace === action.inputNamespace || namespace === action.outputNamespace)
+      fail('Metadata namespace conflicts with an action namespace');
+    if ((action.objectInput || action.inputNamespace === null) && action.input?.some(field => field.wire_name === namespace))
+      fail('Metadata namespace conflicts with an input field');
+    if (action.objectOutput && action.outputNames?.includes(namespace))
+      fail('Metadata namespace conflicts with an output field');
+  }
+  return namespace;
 }
 function assertJson(value: unknown, label: string, seen = new Set<object>()): void {
   if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
@@ -123,7 +160,11 @@ function actionPath(action: Action, values: Options['path']): string {
     }
     // URL parsers normalize dot segments even when their dots are percent encoded.
     if (value === '.' || value === '..') fail(`Unsafe path parameter ${name}`);
-    encoded[wire] = encodeURIComponent(String(value));
+    try {
+      encoded[wire] = encodeURIComponent(String(value));
+    } catch {
+      fail(`Invalid path encoding for ${name}`);
+    }
   }
   return action.path.replace(/\{([^}]+)\}/g, (_match, name: string) => {
     const value = encoded[name];
@@ -133,7 +174,7 @@ function actionPath(action: Action, values: Options['path']): string {
 }
 
 /** One send; the executor owns transport, envelope validation and error semantics. */
-export async function executeAction<T>(execute: RequestExecutor, action: Action, options: Options = {}): Promise<RequestResult<T>> {
+export async function executeAction<T, TMeta>(execute: RequestExecutor, action: Action, options: Options = {}, namespace = action.metaNamespace): Promise<ActionResult<T, TMeta>> {
   if (typeof options !== 'object' || options === null || Array.isArray(options)) fail('Action options must be an object');
   const query = action.method === 'GET' || action.method === 'OPTIONS';
   let params = encodeFields(options.params, action.input, query, 'params', action.objectInput ? action.metaNamespace : undefined);
@@ -142,20 +183,20 @@ export async function executeAction<T>(execute: RequestExecutor, action: Action,
     if (objectMeta !== undefined && !isRecord(objectMeta)) fail('Object metadata must be an object');
     const encoded = encodeFields(objectMeta, action.objectInput, query, 'params metadata');
     if (encoded !== undefined) {
-      if (query) fail('Object metadata query input is unsupported by HaveAPI 0.30.2');
+      if (query) fail('Object metadata query input is unsupported by HaveAPI 0.32.0');
       params = params || Object.create(null) as Record<string, unknown>;
-      params[action.metaNamespace] = encoded;
+      params[namespace] = encoded;
     }
   }
   const meta = encodeFields(options.meta, action.globalInput, query, 'meta');
-  if (meta !== undefined && action.inputNamespace === null && params && own(params, action.metaNamespace))
+  if (meta !== undefined && action.inputNamespace === null && params && own(params, namespace))
     fail('Global metadata would overwrite root input metadata');
   const spec: RequestSpec = {
     method: action.method,
     path: actionPath(action, options.path),
     inputNamespace: action.inputNamespace,
     outputNamespace: action.outputNamespace,
-    metaNamespace: action.metaNamespace,
+    metaNamespace: namespace,
     ...(params === undefined ? {} : {params}),
     ...(meta === undefined ? {} : {meta}),
     ...(options.headers === undefined ? {} : {headers: options.headers}),
@@ -165,5 +206,38 @@ export async function executeAction<T>(execute: RequestExecutor, action: Action,
   const response = await execute(spec);
   // The sole response-type narrowing. Application payload fields are unvalidated;
   // preserve the executor's metadata, full envelope and HTTP status receipt.
-  return {...response, data: response.data as T};
+  return {...response, data: canonicalObjectMetadata(response.data, action, namespace) as T, meta: response.meta as TMeta & Record<string, unknown>};
+}
+
+function canonicalObjectMetadata(data: unknown, action: Action, namespace: string): unknown {
+  if (namespace === action.metaNamespace || !action.objectOutput || !Array.isArray(data)) return data;
+  // Only declared object-list metadata positions are projected. Custom payloads,
+  // nested values and the original envelope are never traversed or modified.
+  return data.map(row => isRecord(row) && own(row, namespace) ? {...row, [action.metaNamespace]: row[namespace]} : row);
+}
+
+function descriptionSpec(path: string, metaNamespace: string, options: DescribeOptions): RequestSpec {
+  return {
+    method: 'OPTIONS', path, inputNamespace: null, outputNamespace: null, metaNamespace,
+    ...(options.headers === undefined ? {} : {headers: options.headers}),
+    ...(options.signal === undefined ? {} : {signal: options.signal}),
+    ...(options.timeoutMs === undefined ? {} : {timeoutMs: options.timeoutMs}),
+  };
+}
+function checkDescribeOptions(options: DescribeOptions, action: boolean): void {
+  if (!isRecord(options)) fail('Description options must be an object');
+  for (const key of Object.keys(options)) {
+    if (!['headers', 'signal', 'timeoutMs', ...(action ? ['path'] : [])].includes(key))
+      fail(`Unknown description option ${key}`);
+  }
+}
+/** Live OPTIONS documents use the versioned executor, without auth discovery or caching. */
+export async function describeApi(execute: RequestExecutor, options: DescribeOptions = {}, namespace = <%= literal(@ir.fetch(:metadata_namespace)) %>): Promise<ActionResult<ApiDescription>> {
+  checkDescribeOptions(options, false);
+  return execute(descriptionSpec('/', namespace, options)) as Promise<ActionResult<ApiDescription>>;
+}
+export async function describeAction(execute: RequestExecutor, action: Action, options: DescribeOptions & Pick<Options, 'path'>, namespace = action.metaNamespace): Promise<ActionResult<ActionDescription>> {
+  checkDescribeOptions(options, true);
+  const path = actionPath({...action, path: action.helpPath}, options.path);
+  return execute(descriptionSpec(path, namespace, options)) as Promise<ActionResult<ActionDescription>>;
 }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: haveapi-typescript-client
 version: !ruby/object:Gem::Version
-  version: 0.32.1
+  version: 0.32.2
 platform: ruby
 authors:
 - Jakub Skokan
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.32.1
+        version: 0.32.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.32.1
+        version: 0.32.2
 executables:
 - haveapi-typescript-client
 extensions: []
@@ -48,6 +48,7 @@ files:
 - lib/haveapi/typescript_client/version.rb
 - template/action.ts.erb
 - template/api.ts.erb
+- template/descriptions.ts.erb
 - template/index.ts.erb
 - template/resource.ts.erb
 - template/runtime.ts.erb