@pksep/contracts

Unified messaging contracts for sep-chat microservices.

Exchange = домен. Routing key = entity.event. Суффикс .rpc только для request/reply.

import { ERP, routingKey } from '@pksep/contracts';

amqp.publish(ERP, routingKey('user', 'create'), event);
// exchange: 'erp', routing key: 'user.create'

Install

bun add @pksep/contracts

Architecture

| Exchange | Routing Key | Описание | |----------|-------------|----------| | erp | user.create | Новый пользователь | | erp | user.change | Изменение полей (field diff) | | erp | user.delete | Удаление | | erp | user.ban | Блокировка/разблокировка | | chat | message.new | Новое сообщение | | chat | message.edit | Редактирование | | chat | message.delete | Удаление сообщения | | chat.rpc | message.send | RPC: бот → сообщение | | chat.rpc | user.create | RPC: создать бота | | system | erp.release | Обновление ERP |

Wildcard

user.*       → все события user (create, change, delete, ban)
*.create     → все create в exchange
#            → всё

Examples

Create Event

import { ERP, routingKey, UserCreateEvent } from '@pksep/contracts';

const event: UserCreateEvent = {
  initiatorUserId: 'uuid-admin',
  timestamp: new Date().toISOString(),
  entity: {
    id: 'uuid-new-user',
    initials: 'Иванов И.И.',
    nickname: 'ivanov',
    isBot: false
  }
};

await amqp.publish(ERP, routingKey('user', 'create'), event);

Change Event (field-level diff)

import { ERP, routingKey, EntityChangeEvent } from '@pksep/contracts';

const event: EntityChangeEvent = {
  initiatorUserId: 'uuid-admin',
  timestamp: new Date().toISOString(),
  entity: {
    id: 'uuid-user',
    changeFields: [
      { fieldName: 'nickname', lastValue: 'old_nick', currentValue: 'new_nick' },
      { fieldName: 'avatarUrl', lastValue: null, currentValue: 'https://cdn.example.com/photo.jpg' }
    ]
  }
};

await amqp.publish(ERP, routingKey('user', 'change'), event);

Delete Event

import { ERP, routingKey, EntityDeleteEvent } from '@pksep/contracts';

const event: EntityDeleteEvent = {
  initiatorUserId: 'uuid-admin',
  timestamp: new Date().toISOString(),
  entity: { id: 'uuid-deleted-user' }
};

await amqp.publish(ERP, routingKey('user', 'delete'), event);

Ban Event

import { ERP, routingKey, EntityBanEvent } from '@pksep/contracts';

// Заблокировать
await amqp.publish(ERP, routingKey('user', 'ban'), {
  initiatorUserId: 'uuid-admin',
  timestamp: new Date().toISOString(),
  entity: { id: 'uuid-user', banned: true }
});

// Разблокировать — banned: false

Subscribe (NestJS + @golevelup/nestjs-rabbitmq)

import { ERP, wildcard, EntityCreateEvent, EntityChangeEvent, UserPayload } from '@pksep/contracts';

// Все user events
@RabbitSubscribe({
  exchange: ERP,
  routingKey: wildcard('user'),   // → 'user.*'
  queue: 'my-service.user-events'
})
handleUserEvent(event: EntityCreateEvent<UserPayload> | EntityChangeEvent) { ... }

// Только user.create
@RabbitSubscribe({
  exchange: ERP,
  routingKey: routingKey('user', 'create'),
  queue: 'my-service.user-created'
})
handleUserCreated(event: EntityCreateEvent<UserPayload>) { ... }

// Все create в ERP
@RabbitSubscribe({
  exchange: ERP,
  routingKey: '*.create',
  queue: 'audit.all-creates'
})
handleAnyCreate(event: EntityCreateEvent<{ id: string }>) { ... }

Chat Events

import { CHAT, MessageNewEvent } from '@pksep/contracts';

@RabbitSubscribe({
  exchange: CHAT,
  routingKey: 'message.new',
  queue: 'bot-gateway.chat-events'
})
handleNewMessage(event: MessageNewEvent) { ... }

Bot RPC Commands

import { CHAT_RPC, routingKey, SendMessagePayload, BotCommandResponse } from '@pksep/contracts';

const payload: SendMessagePayload = {
  senderUserId: 'uuid-bot',
  topicId: 'uuid-topic',
  text: 'Hello from bot!'
};

const result = await amqp.request<BotCommandResponse>({
  exchange: CHAT_RPC,
  routingKey: routingKey('message', 'send'),
  payload
});

System Events

import { SYSTEM, routingKey, ReleaseEvent } from '@pksep/contracts';

const release: ReleaseEvent = {
  service: 'erp',
  event: 'release',
  timestamp: new Date().toISOString(),
  data: { version: '2.1.0', severity: 'info' }
};

await amqp.publish(SYSTEM, routingKey('erp', 'release'), release);

Routing Helpers

import { routingKey, wildcard } from '@pksep/contracts';

routingKey('user', 'create')   // → 'user.create'
routingKey('message', 'new')   // → 'message.new'

wildcard('user')               // → 'user.*'
wildcard()                     // → '#'

Structure

src/
├── exchanges.ts        ← ERP, CHAT, CHAT_RPC, SYSTEM
├── routing.ts          ← routingKey(), wildcard()
├── types.ts            ← EntityEvent, FieldChange, SystemEvent, RpcResponse
├── chat/
│   ├── message.ts      ← MessageNewEvent, MessageEditEvent, ...
│   └── rpc.ts          ← SendMessagePayload, BotCommandResponse, queues
├── erp/
│   └── user.ts         ← UserPayload, UserCreateEvent, ...
└── system/
    └── events.ts       ← ReleaseEvent

Docs

• doc/development-guide.md — архитектура, добавление сущностей/доменов, правила именования, чеклист

Publish

npm version patch
bun run build
npm publish --access restricted