api-codegen/README.md

# @gromlab/api-codegen

CLI утилита для генерации TypeScript REST-клиента из OpenAPI спецификации.

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

```bash
npx @gromlab/api-codegen -i <INPUT> -o <OUTPUT> [-n <NAME>] [--mode single|split|both]
```

**Аргументы:**
- `-i, --input <path>` - путь к OpenAPI файлу или URL
- `-o, --output <path>` - директория для сохранения файлов
- `-n, --name <name>` - имя монолитного файла без `.ts`
- `--mode <mode>` - режим генерации: `single`, `split`, `both` (по умолчанию `single`)
- `--single-file` - устаревший алиас для `--mode single`

## Примеры

```bash
# Локальный файл
npx @gromlab/api-codegen -i ./openapi.json -o ./src/api

# URL на спецификацию
npx @gromlab/api-codegen -i https://httpbin.org/spec.json -o ./src/api

# Монолитный файл с кастомным именем
npx @gromlab/api-codegen -i ./openapi.json -o ./src/api -n MyApi

# Разложенный tree-shaking friendly клиент
npx @gromlab/api-codegen -i ./openapi.json -o ./src/api --mode split

# Монолит и разложенный клиент одновременно
npx @gromlab/api-codegen -i ./openapi.json -o ./src/api -n MyApi --mode both
```

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

По умолчанию генерируется legacy монолитный клиент для обратной совместимости:

```text
generated/
└── MyApi.ts
```

В режиме `split` генерируется tree-shaking friendly структура:

```text
generated/
├── create-api-client.ts
├── data-contracts.ts
├── http-client.ts
├── index.ts
└── operations/
    ├── index.ts
    ├── get-users.ts
    └── create-user.ts
```

Каждый endpoint лежит в отдельном файле внутри `operations/`.

В режиме `both` генерируются оба варианта рядом.

## Пример Использования

Для `single` режима:

```typescript
import { Api, HttpClient } from './generated/MyApi';

const http = new HttpClient({ baseUrl: 'https://api.example.com' });
const api = new Api(http);

const users = await api.users.getAll({});
```

Для `split` режима:

```typescript
import { createApiClient, HttpClient } from './generated';
import { getAll } from './generated/operations/get-all';
import { create } from './generated/operations/create';

const http = new HttpClient({
  baseUrl: 'https://api.example.com',
  securityWorker: (securityData: { token: string } | null) => {
    if (!securityData?.token) {
      return undefined;
    }

    return {
      headers: {
        Authorization: `Bearer ${securityData.token}`,
      },
    };
  },
});

const api = createApiClient(http, {
  users: {
    getAll,
    create,
  },
});

const users = await api.users.getAll({});
const createdUser = await api.users.create({ email, password });
```

Если нужен максимально точечный импорт, operation можно вызвать напрямую:

```typescript
import { HttpClient } from './generated/http-client';
import { getAll } from './generated/operations/get-all';

const http = new HttpClient();
const users = await getAll(http, {});
```

## Разработка

### Сборка

```bash
bun run build
```

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

```bash
bun test
bun run test:unit
bun run test:integration
```

Подробная документация по тестированию в [`tests/README.md`](tests/README.md).

## Лицензия

MIT