haveapi-typescript-client 0.31.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b186bae5d9688166db1bc7d4f2c364e6731a513b45216d89f2043cb0574bce53
+  data.tar.gz: cfb2abb678d80782680f9faadf8f251e438398be33d7bfddda0c4d5181e76f8c
+SHA512:
+  metadata.gz: b5ef31267e2c521a419835232fce76a35f5f9201d74c5d80f8d2a3fbac1d06edf7c29c02830f2362d5a080f28ef4a32561f5d4529de7091bac61578f98e838d2
+  data.tar.gz: ffd998fad046255884700004a42673b1389e60d1d651b61945f051c25f3910e33d76b97583bedd8489b2fa4926e1981204be83476e9f6136ec3887b79050d40c

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+gemspec
+gem 'haveapi-client', path: '../ruby'
+
+group :development, :test do
+  gem 'json', '= 2.21.2'
+  gem 'rake'
+  gem 'rspec'
+  gem 'rubocop', '~> 1.85.0'
+  gem 'rubocop-rspec'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Jakub Skokan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,204 @@
+# TypeScript client generator
+
+Generate a typed TypeScript client for one API version from a saved HaveAPI
+protocol 2 schema. Call resources and actions by name, with types for their
+arguments and results. A request executor connects those calls to the existing
+`haveapi-client` runtime or your application's adapter.
+
+## Install the generator
+
+The generator is packaged as the Ruby gem `haveapi-typescript-client`. Once a
+release containing the generator and shared schema API is available, install it
+with:
+
+```sh
+gem install haveapi-typescript-client
+```
+
+The packaged command is `haveapi-typescript-client`; it accepts the same `fetch`
+and `generate` arguments shown below. Its Ruby `haveapi-client` dependency must
+contain the shared schema API. An older gem in the same version range is not
+sufficient. For unreleased development source, use the checkout setup below.
+See the [release guide](../../doc/agent-instructions/releases.md) for coordinated
+packaging and trusted-publisher setup.
+
+## Prepare the source tools
+
+The generator requires Ruby 3.2 or newer. From the HaveAPI checkout root:
+
+```sh
+nix develop
+BUNDLE_GEMFILE="$PWD/clients/typescript/Gemfile" bundle install
+```
+
+The component bundle uses the Ruby client from the same checkout. Record the
+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`.
+
+## Fetch, save and generate
+
+The example API at `https://example.test/api/v1.0/` has `Widget#Update` at
+`/api/v1.0/widgets/{widget_id}`, a nullable string `name` input and an integer
+`id` output. Replace the example URL, version and resource names with those of
+your API.
+
+From the HaveAPI root:
+
+```sh
+mkdir -p /path/to/widget-client/schema
+BUNDLE_GEMFILE="$PWD/clients/typescript/Gemfile" bundle exec ruby \
+  clients/typescript/bin/haveapi-typescript-client fetch https://example.test/api/v1.0/ \
+  --api-version 1.0 --profile public \
+  --output /path/to/widget-client/schema/api.json
+BUNDLE_GEMFILE="$PWD/clients/typescript/Gemfile" bundle exec ruby \
+  clients/typescript/bin/haveapi-typescript-client generate \
+  --schema /path/to/widget-client/schema/api.json --api-version 1.0 \
+  --output /path/to/widget-client/src/generated
+BUNDLE_GEMFILE="$PWD/clients/typescript/Gemfile" bundle exec ruby \
+  clients/typescript/bin/haveapi-typescript-client generate \
+  --schema /path/to/widget-client/schema/api.json --api-version 1.0 \
+  --output /path/to/widget-client/src/generated --check
+```
+
+The saved schema's parent directory must already exist. Fetch uses the exact
+version URL, including its mount prefix; it does not select a server default.
+The explicit generation version must match the saved snapshot. `--check` reports
+missing or stale output without changing it. Keep handwritten files outside
+`src/generated`.
+
+For Basic capture, set `WIDGET_PASSWORD` in your environment, then run:
+
+```sh
+BUNDLE_GEMFILE="$PWD/clients/typescript/Gemfile" bundle exec ruby \
+  clients/typescript/bin/haveapi-typescript-client fetch https://example.test/api/v1.0/ \
+  --api-version 1.0 --profile basic-user --basic-user demo \
+  --basic-password-env WIDGET_PASSWORD \
+  --output /path/to/widget-client/schema/api.json
+```
+
+For an existing HaveAPI token, set `WIDGET_TOKEN` and run:
+
+```sh
+BUNDLE_GEMFILE="$PWD/clients/typescript/Gemfile" bundle exec ruby \
+  clients/typescript/bin/haveapi-typescript-client fetch https://example.test/api/v1.0/ \
+  --api-version 1.0 --profile token-user --token-env WIDGET_TOKEN \
+  --output /path/to/widget-client/schema/api.json
+```
+
+The two authentication choices are mutually exclusive. Token capture first reads
+anonymous discovery at the same version endpoint, then uses the advertised token
+header. Supply a token you have already acquired. `--profile` labels the capture;
+it does not change authentication. Permissions and enabled plugins determine
+which resources the snapshot contains. Failed capture preserves an existing
+output file.
+
+## Use the generated client
+
+In the application containing the generated files, install the supported runtime
+and a TypeScript compiler:
+
+```sh
+cd /path/to/widget-client
+npm install --save-exact haveapi-client@0.30.2
+npm install --save-dev typescript
+```
+
+Import the local generated entry point:
+
+```ts
+import { AsyncClient } from 'haveapi-client';
+import { createClient } from './src/generated/index.js';
+
+const runtime = new AsyncClient('https://example.test/api/v1.0');
+const api = createClient({ execute: spec => runtime.request(spec) });
+
+const result = await api.widget.update({
+  path: { widget_id: 1 },
+  params: { name: 'new name' },
+});
+console.log(result.data.id);
+```
+
+The executor's base URL includes the mount and API version. Do not add a
+constructor version option: raw `request` calls already use this versioned base.
+Configure authentication through the runtime or your application's adapter;
+generated authentication actions are excluded and permissions still apply.
+
+Pass action arguments in one options object: `path` for resource IDs, `params`
+for input fields, and `meta` for metadata. The same object accepts request
+headers, a timeout and an abort signal. Results contain typed `data`, metadata,
+the response envelope and HTTP status. Runtime errors reject the promise.
+Raw request results cannot be passed to
+`AsyncClient.waitForCompletion`; see the
+[JavaScript runtime guide](../js/README.md#advanced-usage-and-reference).
+
+## Schemas and types
+
+Input is a format 1 snapshot with `api_version`, `protocol_version` (major 2),
+`source_url`, `profile`, `mount_path` and `description`. The description includes
+application resources, authentication discovery, the metadata namespace and
+versioned routes. The source URL records where the schema came from and is never
+contacted during generation. See the
+[snapshot reference](../../doc/agent-instructions/development.md#typescript-snapshots-and-provenance)
+for the format and capture helper.
+
+A snapshot covers the resources visible to its capture profile and plugins.
+Server permissions and validation still apply when you call an action. Review
+snapshots before sharing them; they must not contain credentials or tokens.
+Unsupported schema shapes, unsafe routes and name collisions stop generation
+before output is written. These include input lists, Custom IO formats and
+GET/OPTIONS actions with object-input metadata.
+
+- Omitted input fields stay omitted. Nullable `null`, `false`, zero and empty
+  strings are preserved. Numeric integers and path IDs must be JavaScript safe
+  integers; path strings are also supported. Datetime values remain strings.
+- Custom body input accepts JSON. Custom query input accepts only scalars.
+- Output fields can be absent or null; associations are partial records and
+  Custom output is `unknown`. Generated types do not validate response data.
+
+## Generated files and regeneration
+
+Browse resource and action types in their own modules:
+
+```text
+src/generated/
+  index.ts
+  api.ts
+  runtime.ts
+  types.ts
+  resources/
+    widget/
+      resource.ts
+      actions/
+        update.ts
+      resources/
+        child/
+          resource.ts
+```
+
+Import from `index.ts` in application code. Resource directories and action
+filenames follow the generated accessor names; aliases share their canonical
+action's module. Individual module paths are not stable package exports.
+
+The generator owns the entire `src/generated` directory and records its files in
+`.haveapi-generated.json`. Regeneration replaces owned files and removes stale
+output, including nested directories. It refuses symlinks and foreign files.
+Commit the whole generated tree and manifest together. Regenerate with the
+recorded schema and HaveAPI revision, and keep that generator/client pair
+together when reverting versions.
+
+An interrupted write can leave mixed output. Restore the committed generated
+tree before regenerating. If the first generation was interrupted before an
+ownership manifest was written, preserve that partial directory and generate
+into a fresh empty `src/generated`. Do not edit the manifest to bypass a refusal.
+
+The Ruby server can render examples using this generated interface; see
+[generated documentation profiles](docs/documentation.md).
+
+## Development
+
+See [generator development](../../doc/agent-instructions/development.md#typescript-generator)
+for contributor setup, checks and implementation contracts.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = 'spec/unit/**/*_spec.rb'
+end
+
+task default: :spec

data/bin/haveapi-typescript-client

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/haveapi/typescript_client/cli'
+
+exit HaveAPI::TypeScriptClient::Cli.run

data/docs/documentation.md

@@ -0,0 +1,104 @@
+# Generated TypeScript documentation examples
+
+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
+authentication. The server prepares the SDK model at mount time and renders
+examples when users view the documentation.
+
+## Configure the SDK profile
+
+Register the profile for the same API version as the SDK:
+
+```ruby
+api.documentation_clients('1.0',
+  typescript: {
+    package_name: '@example/widget-client',
+    package_version: '1.2.3',
+    snapshot_path: '/absolute/path/to/widget-client/schema.json'
+  }
+)
+api.mount('/mount/')
+```
+
+`package_name` is an ordinary scoped or unscoped npm package name.
+`package_version` is optional and accepts a concrete SemVer, without ranges or
+tags. Omitting it leaves package-version selection to the package manager; it
+does not prove the package is available. Configure a package that users can
+install through its supported distribution channel.
+
+An optional `snapshot_path` selects the exact saved schema used for the SDK.
+Without it, the server builds the adapter from its complete mounted declaration.
+This private description excludes all defaults, prose and samples. An optional
+`generator_version` must match the installed generator version.
+
+The generator is an optional server dependency. Invalid profile fields, missing
+generator code, unreadable or invalid snapshots and version mismatches reject
+startup without publishing partial profiles. The profile accepts package identity,
+snapshot and generator-version settings. Configure authentication in the client
+runtime. Existing dynamic TypeScript examples remain separate.
+
+## Rendered calls and compatibility
+
+Examples bind the selected API version URL directly:
+
+```ts
+import {AsyncClient} from 'haveapi-client';
+import {createClient} from '@example/widget-client';
+
+const runtime = new AsyncClient('https://api.example.test/mount/v1.0');
+const api = createClient({execute: spec => runtime.request(spec)});
+```
+
+The version and mount belong in the runtime's base URL. Its constructor `version`
+option does not prefix raw requests. Public examples need no setup. Protected
+examples use the runtime's Basic authentication or an existing HaveAPI token,
+with credentials read from `HAVEAPI_USER`, `HAVEAPI_PASSWORD` or `HAVEAPI_TOKEN`.
+Both the saved SDK and current authorized help must advertise the provider;
+token header names must agree. Token acquisition, renewal and OAuth are outside
+this adapter.
+
+The adapter resolves names and aliases from a frozen SDK model. It then checks
+the current user's help, action and filtered sample. Changed routes, methods,
+versions, layouts, namespaces or used field contracts produce a limitation.
+Hidden fields and defaults are not filled from the private model. Unrelated
+optional additions do not prevent a compatible example.
+
+Samples use the existing example DSL. Path arguments follow its declared order;
+input wire names map to generated input names. The DSL has no separate input
+metadata carrier, so actions requiring input metadata produce a limitation.
+Inputs preserve omission, null, false, zero and empty strings. Unsafe integer IDs,
+invalid JSON and structured Custom query values cannot be rendered. Output keys
+remain wire names, with guards for optional, null and unknown values.
+
+Successful examples retain `data`, `meta`, `envelope` and `httpStatus`. Rejection
+examples inspect the runtime's error receipt without printing server diagnostics.
+Requests are not retried. A successful request does not establish completion of
+a server-side operation; raw receipts cannot be passed to `waitForCompletion`.
+
+## Adapter and checks
+
+The generator provides `HaveAPI::TypeScriptClient::Documentation` through
+`require 'haveapi/typescript_client/documentation'`. Its factories accept a full
+description or saved snapshot. `resolve` returns a frozen canonical action;
+`render` returns the server's code or limitation result. Rendering performs no
+file, network, generator or compiler work.
+
+Focused unit checks compile the actual rendered programs against generated
+fixture modules with 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`
+installation:
+
+```sh
+HAVEAPI_TYPESCRIPT_RUNTIME=/absolute/path/to/haveapi-client/dist/haveapi-client.js \
+  HAVEAPI_RELEASE_TOOLS_ONLY=1 nix develop --command bundle exec ruby \
+  clients/typescript/spec/documentation/wire.rb
+```
+
+The harness verifies the runtime artifact's hash, compiles the rendered snippets,
+and runs them against a local server at root and mounted URLs. It checks exact
+requests, Basic and existing-token routing, aliases, nested IDs and rejection
+handling. It downloads no runtime and calls no production API.

data/haveapi-typescript-client.gemspec

@@ -0,0 +1,18 @@
+require_relative 'lib/haveapi/typescript_client/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'haveapi-typescript-client'
+  spec.version = HaveAPI::TypeScriptClient::VERSION
+  spec.authors = ['Jakub Skokan']
+  spec.summary = 'Generate typed TypeScript operations from saved HaveAPI schemas'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+  spec.files = Dir.chdir(__dir__) do
+    Dir['{bin,lib,template}/**/*', 'docs/*.md', 'README.md', 'LICENSE.txt',
+        'Gemfile', 'Rakefile', 'haveapi-typescript-client.gemspec'].select { |path| File.file?(path) }.sort
+  end
+  spec.bindir = 'bin'
+  spec.executables = ['haveapi-typescript-client']
+  spec.require_paths = ['lib']
+  spec.add_dependency 'haveapi-client', '~> 0.31.0'
+end

data/lib/haveapi/typescript_client/cli.rb

@@ -0,0 +1,41 @@
+require 'optparse'
+require_relative '../typescript_client'
+
+module HaveAPI::TypeScriptClient
+  class Cli
+    def self.run(argv = ARGV, out: $stdout, err: $stderr)
+      argv = argv.dup
+      command = argv.shift
+      if command == 'fetch'
+        return HaveAPI::Schema::FetchCommand.run(argv, out:, err:, command_name: 'haveapi-typescript-client')
+      end
+
+      argv.unshift(command) if %w[-h --help].include?(command)
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: haveapi-typescript-client fetch URL [options] | generate --schema FILE --api-version VERSION --output DIR [--check]'
+        opts.on('--schema FILE') { |value| options[:schema] = value }
+        opts.on('--api-version VERSION') { |value| options[:version] = value }
+        opts.on('--output DIR') { |value| options[:output] = value }
+        opts.on('--check', 'Check generated output without writing') { options[:check] = true }
+        opts.on('-h', '--help') do
+          out.puts(opts)
+          return 0
+        end
+      end
+      parser.parse!(argv)
+      raise Error, 'expected generate subcommand and no positional arguments' unless command == 'generate' && argv.empty?
+      raise Error, 'generate requires --schema and --output' unless options[:schema] && options[:output]
+
+      Snapshot.version!(options[:version])
+      schema = Snapshot.load(options[:schema])
+      raise Error, 'requested API version differs from snapshot' unless schema.fetch('api_version') == options[:version]
+
+      Generator.new(schema:).generate(output: options[:output], check: options[:check])
+      0
+    rescue Error, OptionParser::ParseError, SystemCallError => e
+      err.puts("haveapi-typescript-client: #{e.message}")
+      1
+    end
+  end
+end