# @teacinema/contracts

npm-пакет с контрактами для межсервисного взаимодействия: gRPC (протобафы) и события (message broker).

## Установка

```bash
yarn add @teacinema/contracts
```

---

## gRPC сервисы

Для подключения gRPC клиента используй `PROTO_PATHS` и соответствующее имя пакета.

| Сервис | Пакет proto | Описание |
|---|---|---|
| `AuthService` | `auth.v1` | Аутентификация (OTP, токены, Telegram) |
| `AccountService` | `account.v1` | Управление аккаунтом (email, телефон) |
| `UsersService` | `users.v1` | Профили пользователей |

### AuthService — `auth.v1`

| Метод | Запрос | Ответ | Описание |
|---|---|---|---|
| `SendOtp` | `SendOtpRequest` | `SendOtpResponse` | Отправить OTP-код |
| `VerifyOtp` | `VerifyOtpRequest` | `VerifyOtpResponse` | Проверить OTP, получить токены |
| `Refresh` | `RefreshRequest` | `RefreshResponse` | Обновить access/refresh токены |
| `TelegramInit` | `Empty` | `TelegramInitResponse` | Получить ссылку для Telegram-авторизации |
| `TelegramVerify` | `TelegramVerifyRequest` | `TelegramVerifyResponse` | Верифицировать данные от Telegram |
| `TelegramComplete` | `TelegramCompleteRequest` | `TelegramCompleteResponse` | Привязать телефон к Telegram-сессии |
| `TelegramConsume` | `TelegramConsumeRequest` | `TelegramConsumeResponse` | Получить токены из Telegram-сессии |

### AccountService — `account.v1`

| Метод | Запрос | Ответ | Описание |
|---|---|---|---|
| `GetAccount` | `GetAccountRequest` | `GetAccountResponse` | Получить данные аккаунта по ID |
| `InitEmailChange` | `InitEmailChangeRequest` | `InitEmailChangeResponse` | Инициировать смену email |
| `ConfirmEmailChange` | `ConfirmEmailChangeRequest` | `ConfirmEmailChangeResponse` | Подтвердить смену email |
| `InitPhoneChange` | `InitPhoneChangeRequest` | `InitPhoneChangeResponse` | Инициировать смену телефона |
| `ConfirmPhoneChange` | `ConfirmPhoneChangeRequest` | `ConfirmPhoneChangeResponse` | Подтвердить смену телефона |

### UsersService — `users.v1`

| Метод | Запрос | Ответ | Описание |
|---|---|---|---|
| `GetMe` | `GetMeRequest` | `GetMeResponse` | Получить профиль пользователя по ID |
| `CreateUser` | `CreateUserRequest` | `CreateUserResponse` | Создать нового пользователя |
| `PatchUser` | `PatchUserRequest` | `PatchUserResponse` | Обновить данные пользователя (частичное обновление) |

---

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

### 1. Регистрация gRPC клиента

```ts
import { ClientsModule, Transport } from '@nestjs/microservices';
import { PROTO_PATHS } from '@teacinema/contracts';

@Module({
  imports: [
    ClientsModule.register([
      {
        name: 'AUTH_SERVICE',
        transport: Transport.GRPC,
        options: {
          protoPath: PROTO_PATHS.AUTH,
          package: 'auth.v1',
          url: 'localhost:5000',
        },
      },
      {
        name: 'ACCOUNT_SERVICE',
        transport: Transport.GRPC,
        options: {
          protoPath: PROTO_PATHS.ACCOUNT,
          package: 'account.v1',
          url: 'localhost:5001',
        },
      },
      {
        name: 'USERS_SERVICE',
        transport: Transport.GRPC,
        options: {
          protoPath: PROTO_PATHS.USERS,
          package: 'users.v1',
          url: 'localhost:5002',
        },
      },
    ]),
  ],
})
export class AppModule {}
```

### 2. Использование gRPC клиента

Типы клиентов генерируются из proto-файлов и находятся в `gen/`:

```ts
import { Inject, Injectable, OnModuleInit } from '@nestjs/common';
import { ClientGrpc } from '@nestjs/microservices';
import { AuthServiceClient } from '@teacinema/contracts/gen/ts/auth';

@Injectable()
export class AuthProxy implements OnModuleInit {
  private authService: AuthServiceClient;

  constructor(@Inject('AUTH_SERVICE') private client: ClientGrpc) {}

  onModuleInit() {
    this.authService = this.client.getService<AuthServiceClient>('AuthService');
  }

  sendOtp(identifier: string, type: string) {
    return this.authService.sendOtp({ identifier, type });
  }
}
```

### 3. Реализация gRPC сервера

```ts
import { Controller } from '@nestjs/common';
import { GrpcMethod } from '@nestjs/microservices';
import { AuthServiceController, AuthServiceControllerMethods } from '@teacinema/contracts/gen/ts/auth';

@Controller()
@AuthServiceControllerMethods()
export class AuthController implements AuthServiceController {
  @GrpcMethod('AuthService', 'SendOtp')
  sendOtp(request: SendOtpRequest): SendOtpResponse {
    // ...
  }
}
```

---

## События (Message Broker)

Интерфейсы событий для типизированного обмена через брокер сообщений (RabbitMQ, Kafka и др.).

| Интерфейс | Источник | Описание |
|---|---|---|
| `OtpRequestedEvent` | auth-service | Запрос на отправку OTP-кода |
| `EmailChangedEvent` | account-service | Инициация смены email |
| `PhoneChangedEvent` | account-service | Инициация смены телефона |

### Публикация события

```ts
import { OtpRequestedEvent } from '@teacinema/contracts';

client.emit<OtpRequestedEvent>('auth.otp_requested', {
  identifier: '+79001234567',
  code: '123456',
  type: 'phone',
});
```

### Подписка на событие

```ts
import { EventPattern } from '@nestjs/microservices';
import { OtpRequestedEvent } from '@teacinema/contracts';

@Controller()
export class NotificationController {
  @EventPattern('auth.otp_requested')
  handleOtpRequested(data: OtpRequestedEvent) {
    // отправить SMS или email с кодом
  }
}
```

---

## Обновление типов из proto

После изменения `.proto` файлов — пересгенерировать TypeScript типы:

```bash
yarn generate
```

---

## Документация

Сгенерировать HTML-документацию и открыть в браузере:

```bash
yarn docs
open docs/index.html
```