npm package: @pachca/generator
Description: Генератор SDK из OpenAPI-спецификации для TypeScript, Python, Go, Kotlin, Swift и C#.
Latest version: 1.1.2

# @pachca/generator

Генератор SDK из OpenAPI-спецификации для TypeScript, Python, Go, Kotlin, Swift и C#.

## Установка

```bash
npm install -g @pachca/generator
```

## Использование

```bash
# Генерация из Pachca API (по умолчанию)
npx @pachca/generator --output ./sdk --lang typescript,python,go,kotlin,swift,csharp

# Генерация из локального файла
npx @pachca/generator --spec openapi.yaml --output ./sdk --lang typescript

# Генерация из URL
npx @pachca/generator --spec https://example.com/openapi.yaml --output ./sdk --lang go
```

### Параметры

| Флаг | Описание |
|------|----------|
| `--spec` | Путь или URL к OpenAPI 3.0 YAML спецификации (по умолчанию: `https://dev.pachca.com/openapi.yaml`) |
| `--output` | Директория для сгенерированных файлов |
| `--lang` | Целевые языки через запятую: `typescript`, `python`, `go`, `kotlin`, `swift`, `csharp` |

### Программный API

```typescript
import { generate } from '@pachca/generator';

generate('openapi.yaml', './output', ['typescript', 'python']);
```

## Архитектура

```
OpenAPI YAML → @pachca/openapi-parser → IR (transform.ts) → Генераторы языков → Исходные файлы
```

1. **Парсер** (`@pachca/openapi-parser`) — читает OpenAPI YAML, разрешает `$ref`, извлекает эндпоинты и схемы
2. **Трансформер** (`transform.ts`) — преобразует спецификацию в языконезависимое промежуточное представление (IR)
3. **Генераторы** (`lang/*.ts`) — создают идиоматичный код для каждого языка из IR

## Расширения OpenAPI

| Расширение | Уровень | Описание |
|------------|---------|----------|
| `x-error: true` | Schema | Помечает схему как тип ошибки (выбрасывается/возвращается при не-2xx) |
| `x-external-url: "paramName"` | Operation | Генерирует параметр `paramName` для динамических URL (например, загрузка в S3) |
| `x-requirements` | Operation | `auth: false` пропускает заголовок Authorization; `scope`/`plan` для метаданных |
| `x-paginated: true` | Operation | Генерирует хелпер `*All` для автоматической пагинации по всем страницам |
| `x-enum-descriptions` | Schema | Сопоставляет значения enum с человекочитаемыми описаниями |
| `x-param-names` | Parameter | Переопределяет имя параметра в SDK |

## Генерируемые возможности

- **Типобезопасные клиенты** с методами для каждой операции
- **Хелперы курсорной пагинации** (`listChatsAll`, `list_chats_all` и т.д.) для эндпоинтов с `x-paginated`
- **Повторные запросы с `Retry-After`** при 429 Too Many Requests (до 3 попыток с экспоненциальной задержкой)
- **Типы enum** с описаниями
- **Union/дискриминированные типы** (oneOf/anyOf)
- **Разворачивание тела запроса** для обёрток с одним полем
- **Поддержка multipart-загрузки**
- **Аннотации `@deprecated`** из спецификации
- **Конвертация snake/camel case** для идиоматичных имён полей

## Структура вывода

| Язык | Файлы |
|------|-------|
| TypeScript | `types.ts`, `client.ts`, `utils.ts` |
| Python | `models.py`, `client.py`, `utils.py`, `__init__.py` |
| Go | `types.go`, `client.go`, `utils.go` |
| Kotlin | `Models.kt`, `Client.kt` |
| Swift | `Models.swift`, `Client.swift`, `Utils.swift` |
| C# | `Models.cs`, `Client.cs`, `Utils.cs` |

## Тестирование

```bash
bun test
```

Snapshot-тесты сравнивают сгенерированный код с зафиксированными образцами в `tests/*/snapshots/`.

Для обновления snapshot'ов после изменения генераторов:

```bash
bun -e "import { generate } from './src/index.ts'; generate('tests/crud/fixture.yaml', 'tests/crud/snapshots', ['typescript', 'python', 'go', 'kotlin', 'swift', 'csharp']);"
```