Metadata-Version: 2.4
Name: shtab-helpdesk-kafka
Version: 1.0.0
Summary: Server-side Kafka SDK of the Shtab Helpdesk custom channel: customer messages and typing in, operator replies, receipts and conversation states out
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Dist: confluent-kafka==2.16.0
Requires-Dist: msgspec==0.22.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# shtab-helpdesk-kafka — SDK своего канала Helpdesk для Python

Серверный SDK для системы организации, которая сама ведёт чат с клиентом (свой сайт или
приложение), а операторов держит в Shtab Helpdesk. Через Kafka система отправляет в Helpdesk
сообщения клиента и «печатает…», а получает ответы операторов, квитанции о приёме, состояния
обращения и «оператор печатает».

Контракт — JSON Schema `contracts/integrations/custom_channel/*.v1.json`. Структуры пакета
(`shtab_helpdesk_kafka.contract`, msgspec) написаны по ней, тест `tests/test_contract.py` сверяет
их со схемой до поля: набор полей, обязательность, ограничения, перечисления, значения по
умолчанию.

- Python ≥ 3.11.
- [`confluent-kafka`](https://github.com/confluentinc/confluent-kafka-python) 2.16.0 (librdkafka),
  Apache-2.0; [`msgspec`](https://jcristharif.com/msgspec/) 0.22.0, BSD-3-Clause.

## Установка

Пакет скачивается со страницы «Загрузки» портала разработчика
(https://developers.helpdesk.shtab.io/downloads): там адрес файла текущей версии, SHA-256 и
готовая команда установки. Для сборки без интернета тот же файл есть в комплекте поставки.

В комплекте — `shtab_helpdesk_kafka-<версия>-py3-none-any.whl` (собирается `uv build` в каталоге
пакета). `confluent-kafka` и `msgspec` — колёса из PyPI или из зеркала организации (у
`confluent-kafka` librdkafka уже внутри колеса для Linux, macOS и Windows):

```bash
pip install ./shtab_helpdesk_kafka-1.0.0-py3-none-any.whl
# без сети: колёса зависимостей рядом
pip install --no-index --find-links ./wheels ./shtab_helpdesk_kafka-1.0.0-py3-none-any.whl
```

## Подключение

### Брокер Helpdesk

Администратор Helpdesk заводит канал «Kafka» на брокере установки и передаёт:

- адреса брокеров и CA их сертификата;
- учётку `helpdesk-custom-<ref>` (SCRAM-SHA-512) и её пароль;
- топики `<prefix>.custom.<ref>.inbound.v1` (пишете вы) и `<prefix>.custom.<ref>.outbound.v1`
  (читаете вы);
- группы консьюмеров разрешены с префиксом `custom.<ref>.` — например `custom.<ref>.chat`.

```python
from shtab_helpdesk_kafka import (
    Client,
    Config,
    Sasl,
    SaslMechanism,
    SecurityProtocol,
    Tls,
    pem_file,
)

config = Config(
    bootstrap_servers='kafka-1.helpdesk.example:9093,kafka-2.helpdesk.example:9093',
    security_protocol=SecurityProtocol.SASL_SSL,
    sasl=Sasl(SaslMechanism.SCRAM_SHA_512, 'helpdesk-custom-acme', password),
    tls=Tls(ca_pem=pem_file('/etc/helpdesk/kafka-ca.pem')),
    inbound_topic='helpdesk.custom.acme.inbound.v1',
    outbound_topic='helpdesk.custom.acme.outbound.v1',
    group_id='custom.acme.chat',
)
client = Client(config)
```

### Брокер организации

Топики, учётки и группа — ваши; Helpdesk подключается к ним со своей учёткой. Подходит любая
конфигурация брокера:

```python
# mTLS без SASL
Config(
    bootstrap_servers=['kafka.acme.internal:9093'],
    security_protocol=SecurityProtocol.SSL,
    tls=Tls(
        ca_pem=pem_file('ca.pem'),
        cert_pem=pem_file('client.pem'),
        key_pem=pem_file('client.key'),
        key_password=os.environ.get('KEY_PASSWORD', ''),  # если ключ зашифрован
    ),
    inbound_topic='helpdesk-inbound',
    outbound_topic='helpdesk-outbound',
    group_id='chat-backend',
)

# SASL PLAIN поверх TLS; SCRAM-SHA-256 — SaslMechanism.SCRAM_SHA_256
Config(
    bootstrap_servers='kafka.acme.internal:9094',
    security_protocol=SecurityProtocol.SASL_SSL,
    sasl=Sasl(SaslMechanism.PLAIN, 'chat', password),
    tls=Tls(ca_pem=pem_file('ca.pem')),
    inbound_topic='helpdesk-inbound',
    outbound_topic='helpdesk-outbound',
    group_id='chat-backend',
    # свои параметры librdkafka поверх SDK
    extra={'ssl.endpoint.identification.algorithm': 'https'},
)
```

`PLAINTEXT` и `SASL_PLAINTEXT` — только внутри доверенной сети: пароль SCRAM не передаётся
открыто, но сообщения клиентов — да.

| Поле | Что это |
|---|---|
| `bootstrap_servers` | `host:port` списком или строкой через запятую |
| `security_protocol` | `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, `SASL_SSL` |
| `sasl` | `Sasl(mechanism, username, password)`: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512` |
| `tls` | `Tls(ca_pem, cert_pem, key_pem, key_password)` — PEM-тексты; без `ca_pem` — системные CA |
| `inbound_topic` / `outbound_topic` | входной (пишете вы) и выходной (пишет Helpdesk) топики |
| `group_id` | группа консьюмеров выходного топика, нужна для чтения |
| `extra` | параметры librdkafka поверх SDK |

## Отправка

```python
from shtab_helpdesk_kafka import Customer, InboundAttachment

customer = Customer(external_id='client-42', name='Анна Петрова')

# message_id по умолчанию — новый UUID; sent_at — сейчас
message_id = client.send_message(
    customer,
    'Где мой заказ?',
    attachments=[InboundAttachment(url='https://files.acme.example/r/42.pdf', name='чек.pdf')],
    thread_id='order-77',  # необязательно: пусто — одна нить на клиента
)

# Не чаще раза в 3 секунды на (клиент, нить): лишний вызов ничего не шлёт и вернёт False
sent = client.send_typing(customer, draft='Где мой зак')
```

- Ключ записи — `customer.external_id`: всё о клиенте идёт по порядку в одной партиции
  (партиционер `murmur2_random`, как у Java, Go- и JS-SDK).
- Продюсер идемпотентный, `acks=all`: `send_message` возвращается, когда запись подтвердили все
  синхронные реплики (не дольше 30 секунд, иначе исключение).
- Ошибка отправки — повторите с тем же `message_id`: Helpdesk примет сообщение один раз.
- До отправки сообщение проверяется по контракту: длины полей, не больше 10 вложений, текст (не
  из одних пробелов) или хотя бы одно вложение. Иначе — `HelpdeskValidationError` с `issues`.
- `draft` — что клиент набрал; его видит только назначенный оператор при включённом показе набора,
  Helpdesk его не хранит. Без `draft` — только «печатает…».
- `send_message` и `send_typing` можно звать из разных потоков.

## Получение

```python
@client.on_message
def reply(event: OutboundMessage, record: RecordMeta) -> None:
    # фрагмент ответа: текст, файл (event.file) или кнопки (event.quick_replies)
    with db.transaction():
        if db.remember_event(event.event_id):  # уникальный индекс: повтор — False
            chat.show(event.customer.external_id, event)


@client.on_receipt
def receipt(event: Receipt, record: RecordMeta) -> None:
    if event.status == ReceiptStatus.REJECTED:
        chat.mark_failed(event.message_id, event.reason)


@client.on_conversation_state
def state(event: ConversationState, record: RecordMeta) -> None:
    chat.set_status(event.customer.external_id, event.status, event.number)


@client.on_typing
def typing(event: OperatorTyping, record: RecordMeta) -> None:
    chat.show_typing(event.customer.external_id, event.author.name)


@client.on_error
def invalid(error: HelpdeskRecordError) -> None:
    log.warning('invalid record %s', error.record)


with client:  # close() на выходе
    client.run()  # до client.stop() — из обработчика, сигнала или другого потока
```

- Обработчики — декораторы или обычные вызовы `client.on_message(handler)`; на вид один
  обработчик. Вида без обработчика запись просто коммитится.
- `client.poll(timeout)` обрабатывает не больше одной записи — для своего цикла событий.
  `poll`/`run` зовутся из одного потока.
- Новая группа читает выходной топик с начала, дальше — с закоммиченного оффсета.
- Неизвестный `type` (новый вид в будущих версиях Helpdesk) пропускается с предупреждением в лог —
  старый SDK не падает от нового вида. Неизвестные поля известных видов игнорируются.
- Запись не по контракту (не JSON, нет `type`, поля не проходят схему) уходит в `on_error` как
  `HelpdeskRecordError` с исходными байтами `value` и положением `record`; после обработчика она
  коммитится и пропускается. Без `on_error` — пишется в лог.
- Логгер — `logging.getLogger('shtab_helpdesk_kafka')`; в лог не попадают тексты сообщений, только
  положение записи и вид.

### At-least-once и дедупликация

Оффсет коммитится после того, как обработчик завершился без исключения. Исключение обработчика
(или `on_error`) выходит из `poll`/`run`, позиция партиции возвращается на эту запись — следующий
`poll` отдаст её снова.

Поэтому одна и та же запись может прийти дважды: после сбоя обработчика, перезапуска процесса,
перебалансировки группы, повторной отправки самим Helpdesk. Дедуплицируйте по `event_id` — повтор
записи несёт тот же `event_id`. Надёжно — уникальный индекс в вашей БД и запись `event_id` в одной
транзакции с действием. Ответ из нескольких частей (текст, файл, кнопки) приходит несколькими
фрагментами с одним `message_id` и разными `part_index`/`split_index`; у каждого фрагмента свой
`event_id`.

## Пример

`examples/chat_bridge.py` — отправка сообщения и «печатает…», показ ответа оператора, квитанции,
состояния и набора, дедупликация по `event_id`, остановка по `SIGTERM`:

```bash
HELPDESK_KAFKA_BOOTSTRAP=kafka.helpdesk.example:9093 HELPDESK_KAFKA_CA_FILE=ca.pem \
HELPDESK_KAFKA_USERNAME=helpdesk-custom-acme HELPDESK_KAFKA_PASSWORD=… \
HELPDESK_KAFKA_INBOUND_TOPIC=helpdesk.custom.acme.inbound.v1 \
HELPDESK_KAFKA_OUTBOUND_TOPIC=helpdesk.custom.acme.outbound.v1 \
HELPDESK_KAFKA_GROUP=custom.acme.chat uv run python examples/chat_bridge.py
```

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

```bash
uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest
HELPDESK_SDK_KAFKA_SMOKE=1 uv run pytest tests/test_smoke.py   # брокер dev-стенда (make dev)
uv build                                                      # wheel и sdist в dist/
```

Копии схем контракта (`tests/schemas`) и примеры записей (`tests/fixtures`) обновляет
`make sdk-generate` в корне репозитория. Smoke заводит на брокере стенда топики
`sdk-smoke.python.<uuid>.*` учёткой `helpdesk-admin` и удаляет их после прогона; адрес и учётку
меняют `HELPDESK_SDK_KAFKA_BOOTSTRAP`, `…_USERNAME`, `…_PASSWORD`.
