📦 @alexandermo/talent-api-types

Auto-generated TypeScript типы для Talent API's из OpenAPI спецификации.

Полностью типизированные интерфейсы и типы для работы с Talent API's. Типы обновляются автоматически с каждой версией спецификации.

🚀 Быстрый старт

Установка

npm install @alexandermo/talent-api-types

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

Шаг 1: Загрузить типы в проект

npx talent-types fetch talent_v2

Типы будут скопированы в .talent-gen-types/talent-api-v2/

Шаг 2: Импортировать в код

import type { Event, Team, User } from "./.talent-gen-types/talent-api-v2";

const event: Event = {
  id: 1,
  title: "My Event",
  start: new Date(),
  // ... остальные поля с автодополнением
};

Варианты типов

Выбирайте какой вариант типов вам нужен:

# Refined версия (исправленная, рекомендуется) — по умолчанию
npx talent-types fetch talent_v2

# Parsed версия (clean-primitives результат)
npx talent-types fetch talent_v2 --variant=parsed

# Auto версия (сырой Orval результат)
npx talent-types fetch talent_v2 --variant=auto

� Доступные команды

# Список доступных API сервисов
npx talent-types list

# Показать версию пакета
npx talent-types --version

# Справка
npx talent-types --help

📁 Структура типов

После выполнения fetch типы находятся в:

.talent-gen-types/
└── talent-api-v2/
    ├── index.ts              ← Главный экспорт (рекомендуется)
    └── models/               ← Все типы (~110 файлов)
        ├── event.ts
        ├── team.ts
        ├── user.ts
        └── ... еще ~107 файлов

💡 Примеры использования

Базовый пример

import type { Event, EventFormat } from "./.talent-gen-types/talent-api-v2";

// Полная типизация
const event: Event = {
  id: 123,
  title: "Team Standup",
  description: "Daily meeting",
  format: EventFormat.online,
  start: new Date("2026-02-13T10:00:00Z"),
  end: new Date("2026-02-13T10:30:00Z"),
  // IDE подскажет все доступные поля
};

В React компоненте

import React from 'react';
import type { Event, Team } from './.talent-gen-types/talent-api-v2';

interface EventCardProps {
  event: Event;
  team: Team;
}

const EventCard: React.FC<EventCardProps> = ({ event, team }) => {
  return (
    <div className="event-card">
      <h2>{event.title}</h2>
      <p>{event.description}</p>
      <span>{event.format}</span> {/* Автодополнение для enum */}
      <strong>{team.name}</strong>
    </div>
  );
};

С дополнительными типами

import type {
  Event,
  EventCreateBody,
  EventDeferredNotification,
  ConflictResponse,
} from "./.talent-gen-types/talent-api-v2";

// Создание события
const createEventPayload: EventCreateBody = {
  title: "Workshop",
  format: "online",
  start: new Date(),
  // ... остальные обязательные поля
};

// Отложенное уведомление
const notification: EventDeferredNotification = {
  id: "1",
  template_id: "welcome",
  before_start_minutes: 15,
};

🔄 Когда обновлять типы

Пакет отслеживает изменения OpenAPI спецификации. Когда вы запускаете fetch, он:

1. Проверяет если спека изменилась
2. Обновляет типы если нужно
3. Сообщает какой вариант вы используете
4. Показывает как переключиться на другой вариант

$ npx talent-types fetch talent_v2

✅ Types for "Talent API V2" have been fetched successfully
   📁 Path: ./.talent-gen-types/talent-api-v2
   📄 Files: 110
   📌 Variant: refined (исправленная версия)

⚙️ Про варианты типов

🎯 Refined (РЕКОМЕНДУЕТСЯ)

- Описание: Очищенные и оптимизированные типы
- Примитивы встроены в интерфейсы
- ~110 файлов
- Лучшее соотношение читаемости и полноты

📊 Parsed

- Описание: Результат clean-primitives обработки
- Примитивные типы минимизированы
- ~109 файлов
- Максимально компактная структура

🔧 Auto

- Описание: Полное сырое представление из OpenAPI
- Все типы из спецификации как есть
- ~160 файлов (включая вспомогательные типы)
- Наиболее полное покрытие всех деталей

Как выбрать?

| Случай | Вариант | | ---------------------------------- | ------- | | Первый раз используете | refined | | Спека обновилась, а пакет еще нет | parsed | | parsed некорректно генерирует типы | auto | | Не знаете какой выбрать | refined |

🔒 Требования

• Node.js 18.x и выше
• npm 8.x и выше

Проверить версию:

node --version
npm --version

📍 Путь импорта

Рекомендуется всегда импортировать из главного файла:

// ✅ Хорошо — используйте index
import type { Event, Team } from "./.talent-gen-types/talent-api-v2";

// ⚠️ Может работать, но менее удобно
import type { Event } from "./.talent-gen-types/talent-api-v2/models/event";

🚨 Важно знать

Папка .talent-gen-types/ временная

Типы генерируются в .talent-gen-types/, но это рабочая папка. Для production используйте импорты с относительным путем:

// Работает везде
import type { Event } from "./.talent-gen-types/talent-api-v2";

Обновление типов

Чтобы получить свежие типы, просто запустите fetch снова:

# Обновит типы если спека изменилась
npx talent-types fetch talent_v2

🖇️ Интеграция в проект

package.json скрипт

Рекомендуется добавить в package.json:

{
  "scripts": {
    "types:fetch": "talent-types fetch talent_v2",
    "types:list": "talent-types list",
    "setup": "npm install && npm run types:fetch"
  }
}

Тогда новые разработчики просто запустят:

npm run setup

git интеграция

Добавьте в .gitignore:

# Типы генерируются локально
.talent-gen-types/
.talent-types-cache.json

📚 Справочные материалы

• Talent API Документация
• OpenAPI Specification
• TypeScript Handbook
• Orval Documentation

📄 Лицензия

MIT

Версия пакета: 0.0.1
Последнее обновление: 13 февраля 2026 г.
Автор: Jeystyle Team