Metadata-Version: 2.4
Name: kavchat
Version: 0.0.7
Summary: Kavchat server SDK for Python: identity tokens, webhook verification and the Server API
Author-email: maxsave <support@kavchat.com>
License: MIT
Project-URL: Homepage, https://kavchat.com
Project-URL: Documentation, https://kavchat.com/docs/
Keywords: kavchat,chatbot,support,webhook,jwt
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# kavchat (Python)

Kavchat server SDK for Python 3.8+. Standard library only (`urllib`, `hmac`, `hashlib`, `json`), fully type hinted.

## Install

```sh
pip install kavchat
```

## Setup

```python
import os
from kavchat import Kavchat

kavchat = Kavchat(
    os.environ["KAVCHAT_SECRET_KEY"],
    # base_url="https://api.kavchat.com",
    # timeout=30.0,
    # locale="en",  # language of error messages
)
```

## Identify your users

```python
token = kavchat.create_user_token(
    "user_123",                 # required, 1 to 128 characters
    phone="+972501234567",
    name="Dana",
    email="dana@example.com",
    expires_in=7 * 24 * 3600,   # seconds, default 7 days, at most 30 days
)
```

`kavchat.create_user_token(secret_key, user_id, ...)` also exists as a module function.

## Verify webhooks

```python
from flask import Flask, request
from kavchat import WebhookVerificationError

app = Flask(__name__)

@app.post("/kavchat/webhook")
def webhook():
    try:
        event = kavchat.verify_webhook(request.get_data(), request.headers.get("Kavchat-Signature"))
    except WebhookVerificationError as err:
        return err.code, 400
    if event["type"] == "ticket.created":
        print("New ticket", event["data"]["number"])
    return "", 200
```

Pass the raw bytes (`request.get_data()`, or `request.body` in Django). The optional third argument is the tolerance in seconds (default 300).

## Server API

Responses are typed dicts (`kavchat.types`).

```python
kavchat.get_workspace()
kavchat.list_tickets(status="open", limit=50, before=120)
kavchat.get_ticket(ticket_id)
kavchat.set_ticket_status(ticket_id, "closed")
kavchat.get_reports(from_=datetime(2026, 1, 1, tzinfo=timezone.utc), to=datetime.now(timezone.utc))
kavchat.get_settings()
kavchat.update_settings(audience="testers", tester_phones=["+972501234567"])
kavchat.list_releases()
```

Errors raise `KavchatApiError` with `status`, `code`, `message` and `details`. `status` is 0 for `timeout` and `network_error`.

## Tests

```sh
PYTHONPATH=src python3 -m unittest discover -s tests -v
```

## License and support

MIT. Documentation: https://kavchat.com/docs/. Questions: support@kavchat.com.
