kavchat 0.0.4__py3-none-any.whl

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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+kavchat/__init__.py,sha256=-5PVWw85vRKKGtdwx0NthD-F_bVLPEoWMzCj1Rr4W50,643
+kavchat/client.py,sha256=Au4Y2Wsm1q5iDyZNts4lWpRZBBwhBzvWU3q6fA18Uoc,7151
+kavchat/errors.py,sha256=HnxAvElU9yf6N45FgP6w4EcUv5DCTMutZJa9CoHviic,1256
+kavchat/identity.py,sha256=5s564Y21o0gb5SVR2vFA0cbDQaqNFF2ToXL7Y3QUzGI,2311
+kavchat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kavchat/types.py,sha256=I9dEp1URmLtkLI5Kotxh_PMItGSPQ7LSYI8qzApFi3Y,2246
+kavchat/webhook.py,sha256=4A_NCxbVQY2pwsvHPD-40ZKG3g2rQvp1AeDBUIBgqoc,2346
+kavchat-0.0.4.dist-info/licenses/LICENSE,sha256=ywlod2YvbvK17sQVt7mnKduK_kgzjq5owYKBSNyovt8,1064
+kavchat-0.0.4.dist-info/METADATA,sha256=eDiplFW2E5pZGCwyLDQalyD1vfreaH6nsF7Pma5oaSQ,2944
+kavchat-0.0.4.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+kavchat-0.0.4.dist-info/top_level.txt,sha256=ewth_geCmq04KBJ8__Xw6Pb3m8jDGEyGihppzMI-mG8,8
+kavchat-0.0.4.dist-info/RECORD,,

kavchat-0.0.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

kavchat-0.0.4.dist-info/licenses/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.dist-info/top_level.txt

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