@sdk-it/cli 0.46.0 → 0.46.2

package/README.md

@@ -1,110 +1,115 @@
 # @sdk-it/cli
 
-<p align="center">Command-line interface for SDK-IT that generates type-safe client SDKs from OpenAPI specifications</p>
+Generate type-safe client SDKs from OpenAPI specifications.
 
-## Installation
+## Run the CLI
 
-```bash
-# Install globally
-npm install -g @sdk-it/cli
+Use the latest CLI without installing it globally:
 
-# Or use with npx without installing
-npx @sdk-it/cli
+```bash
+npx @sdk-it/cli@latest --help
 ```
 
-## Usage
-
-Generate SDKs from OpenAPI specifications:
-
-### Basic Command Structure
+To pin the CLI in a project:
 
 ```bash
-npx @sdk-it/cli <language> --spec <path-to-spec> --output <output-directory> [options]
+npm install --save-dev @sdk-it/cli
 ```
 
-### Options
-
-| Option        | Alias | Description                                              | Default    |
-| ------------- | ----- | -------------------------------------------------------- | ---------- |
-| `--spec`      | `-s`  | Path to OpenAPI specification file (local or remote URL) | _Required_ |
-| `--output`    | `-o`  | Output directory for the generated SDK                   | _Required_ |
-| `--name`      | `-n`  | Name of the generated client                             | `Client`   |
-| `--mode`      | `-m`  | Generation mode: `full` or `minimal`                     | `minimal`  |
-| `--formatter` |       | Formatter command to run on generated code               |            |
+## Generate a TypeScript SDK
 
-#### Mode Options
+Inside an existing TypeScript project, install the generated client's runtime
+dependencies:
 
-- `minimal`: Generates only the client SDK files (default)
-- `full`: Generates a complete project including package.json and tsconfig.json (useful for monorepo/workspaces)
+```bash
+npm install zod fast-content-type-parse
+```
 
-#### Formatter
+Generate the client:
 
-You can specify a command to format the generated code. The special variable `$SDK_IT_OUTPUT` will be replaced with the output directory path.
+```bash
+npx @sdk-it/cli@latest generate typescript \
+  --spec ./openapi.json \
+  --output ./src/generated/api \
+  --name MyApi \
+  --mode minimal
+```
 
-Examples:
+Use it:
 
-- `--formatter "prettier $SDK_IT_OUTPUT --write"`
-- `--formatter "biome check $SDK_IT_OUTPUT --write"`
+```typescript
+import { MyApi } from './src/generated/api/index.ts';
 
-### Supported Specification Formats
+const client = new MyApi({
+  baseUrl: 'https://api.example.com',
+});
 
-- JSON (`.json`)
-- YAML (`.yaml`, `.yml`)
+const users = await client.request('GET /users', {});
+console.log(users);
+```
 
-## Examples
+`request` returns the unwrapped response data. Invalid inputs and non-successful
+HTTP responses throw typed errors exported by the generated SDK.
 
-### Generate SDK from a Remote OpenAPI Specification
+## TypeScript options
 
-```bash
-npx sdk-it -s https://petstore.swagger.io/v2/swagger.json -o ./client
+```text
+npx @sdk-it/cli@latest generate typescript [options]
 ```
 
-### Generate SDK with Custom Client Name
+| Option                     | Description                                                  | Default   |
+| -------------------------- | ------------------------------------------------------------ | --------- |
+| `--spec`, `-s`             | Local path or remote URL to an OpenAPI JSON or YAML document | Required  |
+| `--output`, `-o`           | Output directory                                             | Required  |
+| `--name`, `-n`             | Generated client class name                                  | `Client`  |
+| `--mode`, `-m`             | `minimal` source files or a `full` standalone project        | `minimal` |
+| `--useTsExtension [value]` | Include `.ts` in generated imports                           | `true`    |
+| `--formatter <command>`    | Command used to format the generated source directory        |           |
+| `--no-default-formatter`   | Skip the default Prettier formatter                          |           |
+| `--readme false`           | Skip the generated API README                                |           |
+| `--pagination <config>`    | Configure pagination, such as `false` or `guess=false`       | `true`    |
+| `--no-install`             | Skip dependency installation in `full` mode                  |           |
+| `--verbose`, `-v`          | Show generator and installation output                       | `false`   |
+
+`minimal` mode writes client source files directly to `--output`. `full` mode
+writes source files under `<output>/src`, adds `package.json` and `tsconfig.json`,
+and installs its runtime dependencies unless `--no-install` is passed.
+
+For a custom formatter, include the generated path explicitly:
 
 ```bash
-npx sdk-it -s ./openapi.json -o ./client -n PetStore
+npx @sdk-it/cli@latest generate typescript \
+  --spec ./openapi.json \
+  --output ./src/generated/api \
+  --formatter "prettier ./src/generated/api --write"
 ```
 
-### Generate Full Project with Formatting
+## Remote specification example
 
 ```bash
-npx sdk-it -s ./openapi.yaml -o ./client -m full --formatter "prettier $SDK_IT_OUTPUT --write"
+npx @sdk-it/cli@latest generate typescript \
+  --spec https://raw.githubusercontent.com/MaximilianKoestler/hcloud-openapi/refs/heads/main/openapi/hcloud.json \
+  --output ./src/generated/hetzner \
+  --name Hetzner \
+  --mode minimal
 ```
 
-## Complete Example
+```typescript
+import { Hetzner } from './src/generated/hetzner/index.ts';
 
-Let's generate a client SDK for the Hetzner Cloud API with automatic formatting:
+const hetzner = new Hetzner({
+  token: process.env.HETZNER_API_TOKEN,
+});
 
-```bash
-# Generate SDK from Hetzner Cloud API spec with Prettier formatting
-npx sdk-it -s https://raw.githubusercontent.com/MaximilianKoestler/hcloud-openapi/refs/heads/main/openapi/hcloud.json -o ./client --formatter "prettier $SDK_IT_OUTPUT --write"
+const result = await hetzner.request('GET /servers', {});
+console.log(result.servers);
 ```
 
-This command:
-
-1. Downloads the OpenAPI specification from the Hetzner Cloud documentation
-2. Generates a type-safe TypeScript SDK in the `./client` directory
-3. Runs Prettier on the generated code for consistent formatting
+## Other generators
 
-Use the generated SDK:
+The same `generate` command also exposes the Dart, Python, API reference, and
+README generators:
 
-```typescript
-import { Client } from './client';
-
-// Create a client instance with your API token
-const client = new Client({
-  baseUrl: 'https://api.hetzner.cloud/v1',
-  headers: {
-    Authorization: 'Bearer your_api_token',
-  },
-});
-
-// Call API methods with type safety
-const [servers, error] = await client.request('GET /servers', {});
-
-if (error) {
-  console.error('Error fetching servers:', error);
-} else {
-  console.log('Servers:', servers);
-}
+```bash
+npx @sdk-it/cli@latest generate --help
 ```

package/dist/bin.js

@@ -816,13 +816,13 @@ Configuring ${generator} generator:`);
     "   npx @sdk-it/cli          # Regenerate SDKs after API changes"
   );
   console.log(
-    "   npx @sdk-it/cli typescript --help # See TypeScript-specific options"
+    "   npx @sdk-it/cli generate typescript --help # See TypeScript-specific options"
   );
   console.log(
-    "   npx @sdk-it/cli python --help     # See Python-specific options"
+    "   npx @sdk-it/cli generate python --help     # See Python-specific options"
   );
   console.log(
-    "   npx @sdk-it/cli dart --help       # See Dart-specific options"
+    "   npx @sdk-it/cli generate dart --help       # See Dart-specific options"
   );
   console.log("\n\u{1F4A1} Tips:");
   console.log(
@@ -959,7 +959,7 @@ import { execFile as execFile2, execSync as execSync2 } from "node:child_process
 import { readdir as readdir2 } from "node:fs/promises";
 import { join as join7 } from "node:path";
 import { snakecase as snakecase2 } from "stringcase";
-import { isEmpty, isRef as isRef2, pascalcase as pascalcase2 } from "@sdk-it/core";
+import { followRef as followRef2, isEmpty as isEmpty2, isRef as isRef2, pascalcase as pascalcase2 } from "@sdk-it/core";
 import {
   createWriterProxy,
   writeFiles
@@ -973,7 +973,14 @@ import {
   toIR
 } from "@sdk-it/spec";
 import { snakecase } from "stringcase";
-import { isRef, notRef, parseRef, pascalcase } from "@sdk-it/core";
+import {
+  followRef,
+  isEmpty,
+  isRef,
+  notRef,
+  parseRef,
+  pascalcase
+} from "@sdk-it/core";
 import { isPrimitiveSchema } from "@sdk-it/spec";
 var dispatcher_default = `"""HTTP dispatcher for making API requests."""
 
@@ -2272,7 +2279,18 @@ var PythonEmitter = class {
     }
     return fieldName;
   }
-  #ref(ref) {
+  #isBottom(schema) {
+    if (!schema) {
+      return false;
+    }
+    const resolved = isRef(schema) ? followRef(this.#spec, schema.$ref) : schema;
+    return !!resolved.not && isEmpty(resolved.not);
+  }
+  #ref(ref, context = {}) {
+    const schema = followRef(this.#spec, ref.$ref);
+    if (this.#isBottom(schema) || schema.type === "array" && this.#isBottom(schema.items)) {
+      return this.handle(schema, context);
+    }
     const cacheKey = ref.$ref;
     const cached = this.#typeCache.get(cacheKey);
     if (cached) {
@@ -2332,27 +2350,25 @@ var PythonEmitter = class {
     }
     for (const [propName, propSchema] of Object.entries(properties)) {
       if (isRef(propSchema)) {
-        this.#ref(propSchema);
-        const refInfo = parseRef(propSchema.$ref);
-        const refName = refInfo.model;
-        const pythonType = pascalcase(refName);
+        const result = this.#ref(propSchema, context);
+        const pythonType = result.type || "Any";
         const fieldName = this.#formatFieldName(propName);
         const isRequired = required.includes(propName);
-        const fieldType = isRequired ? pythonType : `Optional[${pythonType}]`;
-        const defaultValue = isRequired ? "" : " = None";
+        const fieldType = isRequired || result.impossible ? pythonType : `Optional[${pythonType}]`;
+        const defaultValue = isRequired ? "" : result.impossible ? " = Field(default=None, exclude=True)" : " = None";
         fields.push(`    ${fieldName}: ${fieldType}${defaultValue}`);
       } else {
         const result = this.handle(propSchema, { ...context, name: propName });
         const fieldName = this.#formatFieldName(propName);
         const isRequired = required.includes(propName);
         let fieldType = result.type || "Any";
-        if (!isRequired) {
+        if (!isRequired && !result.impossible) {
           fieldType = `Optional[${fieldType}]`;
         }
-        const defaultValue = isRequired ? "" : " = None";
+        const defaultValue = isRequired ? "" : result.impossible ? " = Field(default=None, exclude=True)" : " = None";
         let fieldDef = `    ${fieldName}: ${fieldType}${defaultValue}`;
         if (fieldName !== propName) {
-          fieldDef = `    ${fieldName}: ${fieldType} = Field(alias='${propName}'${defaultValue ? ", default=None" : ""})`;
+          fieldDef = `    ${fieldName}: ${fieldType} = Field(alias='${propName}'${isRequired ? "" : ", default=None"}${!isRequired && result.impossible ? ", exclude=True" : ""})`;
         }
         if (propSchema.description) {
           fieldDef += `  # ${propSchema.description}`;
@@ -2525,7 +2541,18 @@ ${enumItems.join("\n")}
   }
   handle(schema, context = {}) {
     if (isRef(schema)) {
-      return this.#ref(schema);
+      return this.#ref(schema, context);
+    }
+    if (schema.not && isEmpty(schema.not)) {
+      const type = context.pydantic === true ? "_NeverValue" : "Never";
+      return {
+        type,
+        content: "",
+        use: type,
+        fromJson: type,
+        simple: true,
+        impossible: true
+      };
     }
     if ("const" in schema && schema.const !== void 0) {
       return this.#const(schema);
@@ -2609,7 +2636,8 @@ ${docstring}
     (acc, [name, { className, methods }]) => {
       const fileName = `api/${snakecase2(name)}_api.py`;
       const imports = [
-        "from typing import Optional",
+        "from typing import Any, Dict, List, Literal, Optional, Union",
+        "from typing_extensions import Never",
         "import httpx",
         "",
         "from ..http.dispatcher import Dispatcher, RequestConfig",
@@ -2743,7 +2771,7 @@ httpx>=0.24.0,<1.0.0
 pydantic>=2.0.0,<3.0.0
 
 # Enhanced type hints
-typing-extensions>=4.0.0
+typing-extensions>=4.1.0
 
 # Optional: For better datetime handling
 python-dateutil>=2.8.0
@@ -2822,7 +2850,7 @@ ${imports}
 }
 function toInputs(spec, { entry, operation }) {
   const inputName = entry.inputName || "Input";
-  const haveInput = !isEmpty(operation.parameters) || !isEmpty(operation.requestBody);
+  const haveInput = !isEmpty2(operation.parameters) || !isEmpty2(operation.requestBody);
   let contentType = "json";
   if (operation.requestBody && !isRef2(operation.requestBody)) {
     const content = operation.requestBody.content;
@@ -2871,26 +2899,48 @@ function toOutput(spec, operation) {
   }
   const [, mediaType] = jsonContent;
   const schema = mediaType.schema;
-  if (!schema || isRef2(schema)) {
+  if (!schema) {
     return { returnType: "Any", successModel: null, errorModel: null };
   }
+  let outputSchema = schema;
+  if (isRef2(schema)) {
+    const resolvedSchema = followRef2(spec, schema.$ref);
+    const isBottomResponse = isBottomSchema(spec, resolvedSchema) || resolvedSchema.type === "array" && isBottomSchema(spec, resolvedSchema.items);
+    if (!isBottomResponse) {
+      return { returnType: "Any", successModel: null, errorModel: null };
+    }
+    outputSchema = resolvedSchema;
+  }
   const emitter = new PythonEmitter(spec);
-  const result = emitter.handle(schema, {});
+  const result = emitter.handle(outputSchema, {});
   return {
     returnType: result.type || "Any",
-    successModel: result.type,
+    successModel: result.simple ? null : result.type,
     errorModel: null
     // TODO: Handle error models
   };
 }
+function isBottomSchema(spec, schema) {
+  if (!schema) {
+    return false;
+  }
+  const resolved = isRef2(schema) ? followRef2(spec, schema.$ref) : schema;
+  return !!resolved.not && isEmpty2(resolved.not);
+}
 async function serializeModels(spec, emitter) {
   const models = {};
   const standardImports = [
     "from typing import Any, Dict, List, Optional, Union, Literal",
-    "from pydantic import BaseModel, Field",
+    "from typing_extensions import Annotated, Never",
+    "from pydantic import BaseModel, BeforeValidator, Field",
     "from datetime import datetime, date",
     "from uuid import UUID",
-    "from enum import Enum"
+    "from enum import Enum",
+    "",
+    "def _reject_never(value: Any) -> Never:",
+    "    raise ValueError('Value is forbidden by the schema')",
+    "",
+    "_NeverValue = Annotated[Any, BeforeValidator(_reject_never)]"
   ].join("\n");
   emitter.onEmit((name, content, schema) => {
     const fullContent = `${standardImports}
@@ -2909,7 +2959,7 @@ ${content}`;
   if (spec.components?.schemas) {
     for (const [name, schema] of Object.entries(spec.components.schemas)) {
       if (!isRef2(schema)) {
-        emitter.handle(schema, { name });
+        emitter.handle(schema, { name, pydantic: true });
       }
     }
   }
@@ -3110,7 +3160,7 @@ async function emitRemote(spec, options) {
 }
 
 // packages/cli/src/lib/cli.ts
-var generate5 = new Command7("generate").option("-c, --config <path>", "Path to an SDK-IT configuration file").action(async (options) => {
+var generate5 = new Command7("generate").description("Generate SDKs from configuration or OpenAPI").option("-c, --config <path>", "Path to an SDK-IT configuration file").action(async (options) => {
   if (!options.config || options.config.endsWith(".ts")) {
     try {
       const config2 = await loadProjectConfig({ config: options.config });
@@ -3171,7 +3221,7 @@ var generate5 = new Command7("generate").option("-c, --config <path>", "Path to
   await Promise.all(promises);
   console.log("All configured generators completed successfully!");
 }).addCommand(typescript_default).addCommand(python_default).addCommand(dart_default).addCommand(apiref_default).addCommand(readme_default);
-var cli = program.description(`CLI tool to interact with SDK-IT.`).addCommand(generate5, { isDefault: true }).addCommand(init_default).addCommand(
+var cli = program.name("sdk-it").description(`CLI tool to interact with SDK-IT.`).addCommand(generate5, { isDefault: true }).addCommand(init_default).addCommand(
   new Command7("_internal").action(() => {
   }),
   { hidden: true }