kavchat 0.0.4__tar.gz

kavchat-0.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxsave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kavchat-0.0.4/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: kavchat
+Version: 0.0.4
+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.

kavchat-0.0.4/README.md

@@ -0,0 +1,85 @@
+# 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.

kavchat-0.0.4/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kavchat"
+version = "0.0.4"
+description = "Kavchat server SDK for Python: identity tokens, webhook verification and the Server API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "maxsave", email = "support@kavchat.com" }]
+dependencies = []
+keywords = ["kavchat", "chatbot", "support", "webhook", "jwt"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Communications :: Chat",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://kavchat.com"
+Documentation = "https://kavchat.com/docs/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kavchat = ["py.typed"]

kavchat-0.0.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kavchat-0.0.4/src/kavchat/__init__.py

@@ -0,0 +1,19 @@
+"""Kavchat server SDK: identity tokens, webhook verification and the Server API."""
+from .client import DEFAULT_BASE_URL, VERSION, Kavchat
+from .errors import KavchatApiError, KavchatError, WebhookVerificationError
+from .identity import DEFAULT_TOKEN_TTL_SECONDS, MAX_TOKEN_TTL_SECONDS, create_user_token
+from .webhook import SIGNATURE_HEADER, verify_webhook
+
+__version__ = VERSION
+__all__ = [
+    "Kavchat",
+    "KavchatError",
+    "KavchatApiError",
+    "WebhookVerificationError",
+    "create_user_token",
+    "verify_webhook",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TOKEN_TTL_SECONDS",
+    "MAX_TOKEN_TTL_SECONDS",
+    "SIGNATURE_HEADER",
+]

kavchat-0.0.4/src/kavchat/client.py

@@ -0,0 +1,160 @@
+"""Kavchat Server API client (stdlib only)."""
+import json
+import socket
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Union, cast
+
+from .errors import KavchatApiError
+from .identity import DEFAULT_TOKEN_TTL_SECONDS, create_user_token
+from .types import Audience, ReleaseSummary, Report, Settings, Ticket, TicketStatus, WebhookEvent, Workspace
+from .webhook import DEFAULT_TOLERANCE_SECONDS, verify_webhook
+
+DEFAULT_BASE_URL = "https://api.kavchat.com"
+VERSION = "0.0.4"
+
+DateLike = Union[datetime, str]
+
+
+def _iso(value: Optional[DateLike]) -> Optional[str]:
+    if value is None or isinstance(value, str):
+        return value
+    if value.tzinfo is None:
+        value = value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+class Kavchat:
+    """Kavchat server client. Keep the secret key on your backend only.
+
+    >>> kavchat = Kavchat(os.environ["KAVCHAT_SECRET_KEY"])
+    """
+
+    def __init__(
+        self,
+        secret_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        locale: Optional[str] = None,
+    ) -> None:
+        if not isinstance(secret_key, str) or not secret_key:
+            raise ValueError("secret_key is required")
+        self._secret_key = secret_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.locale = locale
+
+    def __repr__(self) -> str:  # never show the key
+        return f"Kavchat(base_url={self.base_url!r})"
+
+    # ------------------------------------------------------------ identity / webhooks
+
+    def create_user_token(
+        self,
+        user_id: str,
+        *,
+        phone: Optional[str] = None,
+        name: Optional[str] = None,
+        email: Optional[str] = None,
+        expires_in: int = DEFAULT_TOKEN_TTL_SECONDS,
+        issued_at: Optional[int] = None,
+    ) -> str:
+        """Sign an identity token for one of your users. See :func:`kavchat.create_user_token`."""
+        return create_user_token(
+            self._secret_key, user_id, phone=phone, name=name, email=email, expires_in=expires_in, issued_at=issued_at
+        )
+
+    def verify_webhook(
+        self,
+        raw_body: Union[str, bytes],
+        signature_header: Optional[str],
+        tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+        *,
+        now: Optional[int] = None,
+    ) -> WebhookEvent:
+        """Verify a webhook request and return the event. See :func:`kavchat.verify_webhook`."""
+        return verify_webhook(self._secret_key, raw_body, signature_header, tolerance_seconds, now=now)
+
+    # ------------------------------------------------------------ Server API
+
+    def get_workspace(self) -> Workspace:
+        return cast(Workspace, self._request("GET", "/workspace"))
+
+    def list_tickets(
+        self, *, status: Optional[TicketStatus] = None, limit: Optional[int] = None, before: Optional[int] = None
+    ) -> List[Ticket]:
+        """Newest first. Page with ``before`` = the number of the last ticket you have."""
+        return cast(List[Ticket], self._request("GET", "/tickets", query={"status": status, "limit": limit, "before": before}))
+
+    def get_ticket(self, ticket_id: str) -> Ticket:
+        return cast(Ticket, self._request("GET", f"/tickets/{urllib.parse.quote(ticket_id, safe='')}"))
+
+    def set_ticket_status(self, ticket_id: str, status: TicketStatus) -> Ticket:
+        path = f"/tickets/{urllib.parse.quote(ticket_id, safe='')}/status"
+        return cast(Ticket, self._request("PUT", path, body={"status": status}))
+
+    def get_reports(self, *, from_: Optional[DateLike] = None, to: Optional[DateLike] = None) -> Report:
+        """Defaults to the last 30 days. ``from_`` has a trailing underscore because ``from`` is reserved."""
+        return cast(Report, self._request("GET", "/reports", query={"from": _iso(from_), "to": _iso(to)}))
+
+    def get_settings(self) -> Settings:
+        return cast(Settings, self._request("GET", "/settings"))
+
+    def update_settings(self, *, audience: Optional[Audience] = None, tester_phones: Optional[List[str]] = None) -> Settings:
+        """Only the audience and the tester phones can be changed from the server."""
+        body: Dict[str, Any] = {}
+        if audience is not None:
+            body["audience"] = audience
+        if tester_phones is not None:
+            body["testerPhones"] = list(tester_phones)
+        return cast(Settings, self._request("PUT", "/settings", body=body))
+
+    def list_releases(self) -> List[ReleaseSummary]:
+        return cast(List[ReleaseSummary], self._request("GET", "/releases"))
+
+    # ------------------------------------------------------------ transport
+
+    def _request(self, method: str, path: str, *, query: Optional[Dict[str, Any]] = None, body: Any = None) -> Any:
+        url = f"{self.base_url}/v1/server{path}"
+        params = {k: str(v) for k, v in (query or {}).items() if v is not None and v != ""}
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        headers = {
+            "Authorization": f"Bearer {self._secret_key}",
+            "Accept": "application/json",
+            "User-Agent": f"kavchat-python/{VERSION}",
+        }
+        if self.locale:
+            headers["Accept-Language"] = self.locale
+        data = None
+        if body is not None:
+            data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                status, raw = res.status, res.read()
+        except urllib.error.HTTPError as err:
+            status, raw = err.code, err.read()
+        except (socket.timeout, TimeoutError):
+            raise KavchatApiError(0, "timeout", f"Request timed out after {self.timeout} s") from None
+        except urllib.error.URLError as err:
+            if isinstance(err.reason, (socket.timeout, TimeoutError)):
+                raise KavchatApiError(0, "timeout", f"Request timed out after {self.timeout} s") from None
+            raise KavchatApiError(0, "network_error", f"Could not reach Kavchat: {err.reason}") from None
+        except OSError as err:
+            raise KavchatApiError(0, "network_error", f"Could not reach Kavchat: {err}") from None
+
+        try:
+            payload = json.loads(raw.decode("utf-8")) if raw else None
+        except (UnicodeDecodeError, ValueError):
+            payload = None
+        if not isinstance(payload, dict) or not (200 <= status < 300) or payload.get("success") is not True:
+            if isinstance(payload, dict) and isinstance(payload.get("code"), str):
+                raise KavchatApiError(status, payload["code"], str(payload.get("message", payload["code"])), payload.get("details"))
+            raise KavchatApiError(status, "invalid_response", f"Unexpected response from Kavchat (HTTP {status})")
+        return payload.get("data")

kavchat-0.0.4/src/kavchat/errors.py

@@ -0,0 +1,40 @@
+"""Errors raised by the Kavchat SDK."""
+from typing import Any, Optional
+
+
+class KavchatError(Exception):
+    """Base class of every error raised by this SDK."""
+
+
+class KavchatApiError(KavchatError):
+    """The Server API answered with an error, or could not be reached.
+
+    ``status`` is the HTTP status, or 0 when no response arrived (``code`` is then
+    ``timeout`` or ``network_error``).
+    """
+
+    def __init__(self, status: int, code: str, message: str, details: Any = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"KavchatApiError(status={self.status!r}, code={self.code!r}, message={self.message!r})"
+
+
+class WebhookVerificationError(KavchatError):
+    """A webhook request failed verification. Answer it with HTTP 400.
+
+    ``code`` is one of ``malformed_header``, ``timestamp_out_of_range``,
+    ``invalid_signature`` or ``invalid_payload``.
+    """
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+__all__ = ["KavchatError", "KavchatApiError", "WebhookVerificationError"]

kavchat-0.0.4/src/kavchat/identity.py

@@ -0,0 +1,62 @@
+"""Identity tokens: HS256 JWTs signed with the secret key, built with the standard library."""
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Optional
+
+DEFAULT_TOKEN_TTL_SECONDS = 7 * 24 * 60 * 60
+MAX_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60
+
+# base64url of {"alg":"HS256","typ":"JWT"}
+_HEADER = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _utf16_length(value: str) -> int:
+    # The server counts characters as JavaScript does (UTF-16 code units).
+    return len(value.encode("utf-16-le")) // 2
+
+
+def create_user_token(
+    secret_key: str,
+    user_id: str,
+    *,
+    phone: Optional[str] = None,
+    name: Optional[str] = None,
+    email: Optional[str] = None,
+    expires_in: int = DEFAULT_TOKEN_TTL_SECONDS,
+    issued_at: Optional[int] = None,
+) -> str:
+    """Sign an identity token for one of your users.
+
+    ``expires_in`` is in seconds (default 7 days, at most 30 days). ``issued_at`` is
+    unix seconds and defaults to now.
+    """
+    if not isinstance(secret_key, str) or not secret_key:
+        raise ValueError("secret_key is required")
+    if not isinstance(user_id, str) or not 1 <= _utf16_length(user_id) <= 128:
+        raise ValueError("user_id must be a string of 1 to 128 characters")
+    if isinstance(expires_in, bool) or not isinstance(expires_in, int) or not 0 < expires_in <= MAX_TOKEN_TTL_SECONDS:
+        raise ValueError(f"expires_in must be a whole number of seconds between 1 and {MAX_TOKEN_TTL_SECONDS}")
+    iat = int(time.time()) if issued_at is None else int(issued_at)
+
+    # Claim order is fixed (sub, phone, name, email, iat, exp) so every SDK signs the same bytes.
+    claims: Dict[str, Any] = {"sub": user_id}
+    if phone:
+        claims["phone"] = phone
+    if name:
+        claims["name"] = name
+    if email:
+        claims["email"] = email
+    claims["iat"] = iat
+    claims["exp"] = iat + expires_in
+
+    payload = _b64url(json.dumps(claims, ensure_ascii=False, separators=(",", ":")).encode("utf-8"))
+    signing_input = f"{_HEADER}.{payload}".encode("ascii")
+    signature = _b64url(hmac.new(secret_key.encode("utf-8"), signing_input, hashlib.sha256).digest())
+    return f"{_HEADER}.{payload}.{signature}"

kavchat-0.0.4/src/kavchat/types.py

@@ -0,0 +1,108 @@
+"""Typed shapes of Server API responses (plain dicts at runtime)."""
+from typing import Any, Dict, List, Literal, Optional, TypedDict
+
+TicketStatus = Literal["open", "closed"]
+Audience = Literal["off", "testers", "all"]
+
+
+# "from" is a Python keyword, so these two use the functional TypedDict syntax.
+TranscriptEntry = TypedDict(
+    "TranscriptEntry",
+    {"from": Literal["bot", "user"], "text": str, "stepId": str, "at": str},
+    total=False,
+)
+
+
+class Ticket(TypedDict, total=False):
+    id: str
+    number: int
+    status: TicketStatus
+    name: Optional[str]
+    email: Optional[str]
+    phone: Optional[str]
+    userId: Optional[str]
+    topicId: Optional[str]
+    topicName: Optional[str]
+    scriptId: Optional[str]
+    sessionId: Optional[str]
+    message: str
+    transcript: List[TranscriptEntry]
+    createdAt: str
+    updatedAt: str
+
+
+class ContactTopic(TypedDict):
+    id: str
+    name: str
+
+
+class Settings(TypedDict, total=False):
+    enabled: bool
+    audience: Audience
+    testerPhones: List[str]
+    botName: str
+    avatarText: str
+    avatarImageUrl: Optional[str]
+    subtitle: str
+    primaryColor: str
+    position: Literal["start", "end"]
+    contactTopics: List[ContactTopic]
+
+
+class Workspace(TypedDict, total=False):
+    id: str
+    name: str
+    locale: str
+    defaultCountry: str
+    plan: str
+    publicKey: str
+    secretKeyHint: str
+    webhookUrl: Optional[str]
+
+
+class ReleaseScript(TypedDict, total=False):
+    id: str
+    kind: str
+    name: str
+
+
+class ReleaseSummary(TypedDict, total=False):
+    version: int
+    note: str
+    restoredFrom: int
+    publishedAt: str
+    scripts: List[ReleaseScript]
+
+
+class ReportTotals(TypedDict, total=False):
+    sessions: int
+    open: int
+    answered: int
+    contact: int
+    abandoned: int
+
+
+class UnmatchedQuestion(TypedDict, total=False):
+    groupKey: str
+    sample: str
+    count: int
+    lastAt: str
+
+
+Report = TypedDict(
+    "Report",
+    {
+        "from": str,
+        "to": str,
+        "totals": ReportTotals,
+        "byScript": List[Dict[str, Any]],
+        "dropOff": List[Dict[str, Any]],
+        "unmatched": List[UnmatchedQuestion],
+    },
+    total=False,
+)
+
+
+class WebhookEvent(TypedDict):
+    type: Literal["ticket.created"]
+    data: Ticket

kavchat-0.0.4/src/kavchat/webhook.py

@@ -0,0 +1,58 @@
+"""Webhook verification for the ``Kavchat-Signature`` header."""
+import hashlib
+import hmac
+import json
+import time
+from typing import List, Optional, Union, cast
+
+from .errors import WebhookVerificationError
+from .types import WebhookEvent
+
+SIGNATURE_HEADER = "Kavchat-Signature"
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def verify_webhook(
+    secret_key: str,
+    raw_body: Union[str, bytes],
+    signature_header: Optional[str],
+    tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+    *,
+    now: Optional[int] = None,
+) -> WebhookEvent:
+    """Check the signature of a webhook request and return the parsed event.
+
+    ``raw_body`` must be the exact bytes received, before any JSON parsing.
+    Raises :class:`WebhookVerificationError` when the request is not authentic or too old.
+    """
+    timestamp: Optional[int] = None
+    bad_timestamp = False
+    signatures: List[str] = []
+    for part in (signature_header or "").split(","):
+        key, sep, value = part.partition("=")
+        if not sep:
+            continue
+        key, value = key.strip(), value.strip()
+        if key == "t":
+            if value.isascii() and value.isdigit():
+                timestamp = int(value)
+            else:
+                bad_timestamp = True
+        elif key == "v1" and value:
+            signatures.append(value)
+    if timestamp is None or bad_timestamp or not signatures:
+        raise WebhookVerificationError("malformed_header", "Kavchat-Signature header is missing or malformed")
+
+    current = int(time.time()) if now is None else int(now)
+    if abs(current - timestamp) > tolerance_seconds:
+        raise WebhookVerificationError("timestamp_out_of_range", "Webhook timestamp is outside the tolerance")
+
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else bytes(raw_body)
+    expected = hmac.new(secret_key.encode("utf-8"), f"{timestamp}.".encode("ascii") + body, hashlib.sha256).hexdigest()
+    if not any(hmac.compare_digest(expected.encode("ascii"), sig.encode("utf-8")) for sig in signatures):
+        raise WebhookVerificationError("invalid_signature", "Webhook signature does not match")
+
+    try:
+        return cast(WebhookEvent, json.loads(body.decode("utf-8")))
+    except (UnicodeDecodeError, ValueError):
+        raise WebhookVerificationError("invalid_payload", "Webhook body is not valid JSON") from None

kavchat-0.0.4/src/kavchat.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: kavchat
+Version: 0.0.4
+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.

kavchat-0.0.4/src/kavchat.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/kavchat/__init__.py
+src/kavchat/client.py
+src/kavchat/errors.py
+src/kavchat/identity.py
+src/kavchat/py.typed
+src/kavchat/types.py
+src/kavchat/webhook.py
+src/kavchat.egg-info/PKG-INFO
+src/kavchat.egg-info/SOURCES.txt
+src/kavchat.egg-info/dependency_links.txt
+src/kavchat.egg-info/top_level.txt
+tests/test_client.py
+tests/test_vectors.py

kavchat-0.0.4/src/kavchat.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kavchat-0.0.4/src/kavchat.egg-info/top_level.txt

@@ -0,0 +1 @@
+kavchat

kavchat-0.0.4/tests/test_client.py

@@ -0,0 +1,120 @@
+import json
+import socket
+import threading
+import unittest
+import urllib.parse
+from datetime import datetime, timezone
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+from kavchat import Kavchat, KavchatApiError
+
+SECRET = "sk_live_client_test_key"
+TICKET = {"id": "abc", "number": 3, "status": "open", "message": "hi", "transcript": []}
+
+
+class _Handler(BaseHTTPRequestHandler):
+    requests = []
+
+    def log_message(self, *args):
+        pass
+
+    def _send(self, status, payload, raw=None):
+        data = raw if raw is not None else json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def _handle(self):
+        url = urllib.parse.urlsplit(self.path)
+        length = int(self.headers.get("Content-Length") or 0)
+        body = json.loads(self.rfile.read(length)) if length else None
+        self.requests.append({"method": self.command, "path": url.path, "query": dict(urllib.parse.parse_qsl(url.query)), "headers": dict(self.headers), "body": body})
+        if self.headers.get("Authorization") != f"Bearer {SECRET}":
+            return self._send(401, {"success": False, "code": "invalid_key", "message": "Invalid key"})
+        p = url.path
+        if p == "/v1/server/tickets/missing":
+            return self._send(404, {"success": False, "code": "ticket_not_found", "message": "Not found", "details": {"id": "missing"}})
+        if p == "/v1/server/releases":
+            return self._send(502, None, raw=b"<html>bad gateway</html>")
+        if p == "/v1/server/tickets":
+            return self._send(200, {"success": True, "data": [TICKET]})
+        if p.startswith("/v1/server/tickets/"):
+            return self._send(200, {"success": True, "data": dict(TICKET, status=(body or {}).get("status", "open"))})
+        if p == "/v1/server/workspace":
+            return self._send(200, {"success": True, "data": {"id": "w1", "name": "Acme"}})
+        if p == "/v1/server/reports":
+            return self._send(200, {"success": True, "data": {"totals": {"sessions": 2}}})
+        if p == "/v1/server/settings":
+            return self._send(200, {"success": True, "data": {"audience": (body or {}).get("audience", "all")}})
+        return self._send(404, {"success": False, "code": "not_found", "message": "nope"})
+
+    do_GET = _handle
+    do_PUT = _handle
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), _Handler)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.base_url = f"http://127.0.0.1:{cls.server.server_address[1]}/"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def test_every_endpoint(self):
+        k = Kavchat(SECRET, base_url=self.base_url, locale="he")
+        self.assertEqual(k.get_workspace()["name"], "Acme")
+        self.assertEqual(k.list_tickets(status="open", limit=10, before=99)[0]["number"], 3)
+        self.assertEqual(k.get_ticket("a/b")["id"], "abc")
+        self.assertEqual(k.set_ticket_status("abc", "closed")["status"], "closed")
+        self.assertEqual(k.get_reports(from_=datetime(2026, 1, 1, tzinfo=timezone.utc), to="2026-02-01T00:00:00Z")["totals"]["sessions"], 2)
+        self.assertEqual(k.get_settings()["audience"], "all")
+        self.assertEqual(k.update_settings(audience="testers", tester_phones=["+972501234567"])["audience"], "testers")
+
+        ws, lst, one, status, reports, settings, update = _Handler.requests[-7:]
+        self.assertEqual(ws["path"], "/v1/server/workspace")
+        self.assertEqual(ws["headers"]["Authorization"], f"Bearer {SECRET}")
+        self.assertEqual(ws["headers"]["Accept-Language"], "he")
+        self.assertTrue(ws["headers"]["User-Agent"].startswith("kavchat-python/"))
+        self.assertEqual(lst["query"], {"status": "open", "limit": "10", "before": "99"})
+        self.assertEqual(one["path"], "/v1/server/tickets/a%2Fb")
+        self.assertEqual((status["method"], status["path"], status["body"]), ("PUT", "/v1/server/tickets/abc/status", {"status": "closed"}))
+        self.assertEqual(reports["query"], {"from": "2026-01-01T00:00:00.000Z", "to": "2026-02-01T00:00:00Z"})
+        self.assertEqual(settings["method"], "GET")
+        self.assertEqual((update["method"], update["body"]), ("PUT", {"audience": "testers", "testerPhones": ["+972501234567"]}))
+
+    def test_api_errors(self):
+        k = Kavchat(SECRET, base_url=self.base_url)
+        with self.assertRaises(KavchatApiError) as ctx:
+            k.get_ticket("missing")
+        e = ctx.exception
+        self.assertEqual((e.status, e.code, e.message, e.details), (404, "ticket_not_found", "Not found", {"id": "missing"}))
+        with self.assertRaises(KavchatApiError) as ctx:
+            Kavchat("sk_live_wrong", base_url=self.base_url).get_workspace()
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (401, "invalid_key"))
+        with self.assertRaises(KavchatApiError) as ctx:
+            k.list_releases()
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (502, "invalid_response"))
+
+    def test_timeout_and_network_errors(self):
+        silent = socket.socket()
+        silent.bind(("127.0.0.1", 0))
+        silent.listen(1)  # accepts the connection and never answers
+        try:
+            with self.assertRaises(KavchatApiError) as ctx:
+                Kavchat(SECRET, base_url=f"http://127.0.0.1:{silent.getsockname()[1]}", timeout=0.2).get_workspace()
+            self.assertEqual((ctx.exception.status, ctx.exception.code), (0, "timeout"))
+        finally:
+            silent.close()
+        with self.assertRaises(KavchatApiError) as ctx:
+            Kavchat(SECRET, base_url="http://127.0.0.1:1").get_workspace()
+        self.assertEqual((ctx.exception.status, ctx.exception.code), (0, "network_error"))
+
+
+if __name__ == "__main__":
+    unittest.main()

kavchat-0.0.4/tests/test_vectors.py

@@ -0,0 +1,68 @@
+import base64
+import json
+import time
+import unittest
+from pathlib import Path
+
+from kavchat import Kavchat, WebhookVerificationError, create_user_token, verify_webhook
+
+VECTORS = Path(__file__).resolve().parents[2] / "test-vectors"
+IDENTITY = json.loads((VECTORS / "identity.json").read_text("utf-8"))
+WEBHOOK = json.loads((VECTORS / "webhook.json").read_text("utf-8"))
+
+
+def _kwargs(data):
+    out = {"phone": data.get("phone"), "name": data.get("name"), "email": data.get("email")}
+    if "expiresIn" in data:
+        out["expires_in"] = data["expiresIn"]
+    return out
+
+
+class IdentityVectors(unittest.TestCase):
+    def test_valid(self):
+        for v in IDENTITY["valid"]:
+            with self.subTest(v["name"]):
+                token = create_user_token(IDENTITY["secretKey"], v["input"]["userId"], issued_at=IDENTITY["iat"], **_kwargs(v["input"]))
+                self.assertEqual(token, v["token"])
+
+    def test_invalid(self):
+        for v in IDENTITY["invalid"]:
+            with self.subTest(v["name"]):
+                with self.assertRaises(ValueError):
+                    create_user_token(IDENTITY["secretKey"], v["input"]["userId"], issued_at=IDENTITY["iat"], **_kwargs(v["input"]))
+
+    def test_default_issued_at_is_now(self):
+        token = create_user_token("sk_live_x", "u")
+        part = token.split(".")[1]
+        claims = json.loads(base64.urlsafe_b64decode(part + "=" * (-len(part) % 4)))
+        self.assertLess(abs(claims["iat"] - time.time()), 5)
+        self.assertEqual(claims["exp"] - claims["iat"], 7 * 24 * 3600)
+
+
+class WebhookVectors(unittest.TestCase):
+    def test_valid(self):
+        for v in WEBHOOK["valid"]:
+            for body in (v["body"], v["body"].encode("utf-8")):
+                with self.subTest(v["name"], body_type=type(body).__name__):
+                    event = verify_webhook(WEBHOOK["secretKey"], body, v["header"], v["toleranceSeconds"], now=v["now"])
+                    self.assertEqual(event["type"], v["expectedType"])
+                    self.assertEqual(event["data"]["number"], v["expectedTicketNumber"])
+
+    def test_invalid(self):
+        for v in WEBHOOK["invalid"]:
+            with self.subTest(v["name"]):
+                with self.assertRaises(WebhookVerificationError) as ctx:
+                    verify_webhook(WEBHOOK["secretKey"], v["body"], v["header"], v["toleranceSeconds"], now=v["now"])
+                self.assertEqual(ctx.exception.code, v["expectedError"])
+
+    def test_client_methods(self):
+        client = Kavchat(IDENTITY["secretKey"])
+        v = IDENTITY["valid"][1]
+        self.assertEqual(client.create_user_token(v["input"]["userId"], issued_at=IDENTITY["iat"], **_kwargs(v["input"])), v["token"])
+        w = WEBHOOK["valid"][0]
+        self.assertEqual(client.verify_webhook(w["body"], w["header"], now=w["now"])["type"], "ticket.created")
+        self.assertNotIn(IDENTITY["secretKey"], repr(client))
+
+
+if __name__ == "__main__":
+    unittest.main()