hatang 0.1.0__py3-none-any.whl

hatang/__init__.py

@@ -0,0 +1,31 @@
+"""Official Python SDK for Ha Tang (hatang.dev).
+
+    from hatang import Hatang
+
+    hatang = Hatang()  # HATANG_API_KEY
+    hatang.chat.subscriptions.upsert("web", "sub_123", {"status": "active", "external_user_id": "u1"})
+"""
+
+from ._client import DEFAULT_BASE_URL
+from ._errors import HatangError, HatangSignatureError
+from ._hatang import AsyncHatang, Hatang
+from ._version import VERSION
+from .helpers import identity_hash, purchase_token
+from .webhooks import construct_ipn_event, construct_webhook_event, verify_ipn, verify_webhook
+
+__version__ = VERSION
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "VERSION",
+    "AsyncHatang",
+    "Hatang",
+    "HatangError",
+    "HatangSignatureError",
+    "construct_ipn_event",
+    "construct_webhook_event",
+    "identity_hash",
+    "purchase_token",
+    "verify_ipn",
+    "verify_webhook",
+]

hatang/_client.py

@@ -0,0 +1,150 @@
+"""The HTTP layer shared by ``Hatang`` and ``AsyncHatang``: headers, query strings, errors."""
+
+from __future__ import annotations
+
+import os
+import platform
+from typing import Any, Dict, Mapping, Optional, Union
+from urllib.parse import quote
+
+import httpx
+
+from ._errors import HatangError
+from ._version import VERSION
+
+DEFAULT_BASE_URL = "https://api.hatang.dev"
+DEFAULT_TIMEOUT = 30.0
+
+JSON = Dict[str, Any]
+Query = Mapping[str, Any]
+
+
+def seg(value: str) -> str:
+    """One path segment: ids may hold ``/`` (Play purchase tokens, your own order ids)."""
+    return quote(str(value), safe="")
+
+
+def query_params(params: Optional[Query]) -> Dict[str, str]:
+    """Query parameters as the API reads them: None dropped, booleans as true/false, lists comma-joined."""
+    out: Dict[str, str] = {}
+    for key, value in (params or {}).items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            out[key] = "true" if value else "false"
+        elif isinstance(value, (list, tuple)):
+            out[key] = ",".join(str(v) for v in value)
+        else:
+            out[key] = str(value)
+    return out
+
+
+class _Config:
+    def __init__(
+        self,
+        api_key: Optional[str],
+        base_url: Optional[str],
+        environment: Optional[str],
+        user_agent: Optional[str],
+    ) -> None:
+        key = api_key or os.environ.get("HATANG_API_KEY")
+        if not key:
+            raise ValueError('Missing API key. Pass it to the constructor: Hatang("ht_123"), or set HATANG_API_KEY')
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get("HATANG_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.environment = environment or os.environ.get("HATANG_ENVIRONMENT")
+        self.user_agent = user_agent or f"hatang-sdk-python/{VERSION} (python/{platform.python_version()})"
+
+    def headers(self, has_body: bool, extra: Optional[Mapping[str, str]]) -> Dict[str, str]:
+        h = {"Authorization": f"Bearer {self.api_key}", "User-Agent": self.user_agent, "Accept": "application/json"}
+        if self.environment:
+            h["Hatang-Environment"] = self.environment
+        if has_body:
+            h["Content-Type"] = "application/json"
+        h.update(extra or {})
+        return h
+
+
+def _parse(res: httpx.Response) -> Any:
+    try:
+        body: Any = res.json() if res.content else None
+    except ValueError:
+        body = None
+    if res.is_success:
+        return body if body is not None else {}
+    err: Mapping[str, Any] = body if isinstance(body, dict) else {}
+    raise HatangError(
+        int(err.get("statusCode") or res.status_code),
+        str(err.get("name") or "application_error"),
+        str(err.get("message") or res.reason_phrase or "Request failed"),
+    )
+
+
+def _unreachable(error: Exception) -> HatangError:
+    return HatangError(0, "application_error", f"Unable to reach the API: {error}")
+
+
+RequestHeaders = Optional[Mapping[str, str]]
+Body = Union[JSON, list, None]  # type: ignore[type-arg]
+
+
+class SyncTransport:
+    def __init__(self, config: _Config, timeout: float, http_client: Optional[httpx.Client]) -> None:
+        self._config = config
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+    def request(self, method: str, path: str, body: Body = None, query: Optional[Query] = None, headers: RequestHeaders = None) -> Any:
+        try:
+            res = self._http.request(
+                method,
+                f"{self._config.base_url}{path}",
+                params=query_params(query),
+                json=body,
+                headers=self._config.headers(body is not None, headers),
+            )
+        except httpx.HTTPError as error:
+            raise _unreachable(error) from error
+        return _parse(res)
+
+    def text(self, path: str, query: Optional[Query] = None) -> Any:
+        try:
+            res = self._http.get(f"{self._config.base_url}{path}", params=query_params(query), headers=self._config.headers(False, None))
+        except httpx.HTTPError as error:
+            raise _unreachable(error) from error
+        if not res.is_success:
+            _parse(res)
+        return res.text
+
+    def close(self) -> None:
+        self._http.close()
+
+
+class AsyncTransport:
+    def __init__(self, config: _Config, timeout: float, http_client: Optional[httpx.AsyncClient]) -> None:
+        self._config = config
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+
+    async def request(self, method: str, path: str, body: Body = None, query: Optional[Query] = None, headers: RequestHeaders = None) -> Any:
+        try:
+            res = await self._http.request(
+                method,
+                f"{self._config.base_url}{path}",
+                params=query_params(query),
+                json=body,
+                headers=self._config.headers(body is not None, headers),
+            )
+        except httpx.HTTPError as error:
+            raise _unreachable(error) from error
+        return _parse(res)
+
+    async def text(self, path: str, query: Optional[Query] = None) -> Any:
+        try:
+            res = await self._http.get(f"{self._config.base_url}{path}", params=query_params(query), headers=self._config.headers(False, None))
+        except httpx.HTTPError as error:
+            raise _unreachable(error) from error
+        if not res.is_success:
+            _parse(res)
+        return res.text
+
+    async def aclose(self) -> None:
+        await self._http.aclose()

hatang/_errors.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+
+class HatangError(Exception):
+    """An API call that did not succeed.
+
+    ``status_code`` is the HTTP status, or 0 when Ha Tang was not reached (network error, timeout).
+    ``name`` is the API's error code (``validation_error``, ``not_found``, ``rate_limit_exceeded``…).
+    """
+
+    def __init__(self, status_code: int, name: str, message: str) -> None:
+        super().__init__(f"{status_code} {name}: {message}")
+        self.status_code = status_code
+        self.name = name
+        self.message = message
+
+    @property
+    def retryable(self) -> bool:
+        """True for outages worth retrying: unreachable, rate limited, or a server error."""
+        return self.status_code == 0 or self.status_code == 429 or self.status_code >= 500
+
+
+class HatangSignatureError(Exception):
+    """A webhook or IPN whose signature (or timestamp) does not match."""

hatang/_hatang.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Awaitable, Optional, Type
+
+import httpx
+
+from ._client import DEFAULT_TIMEOUT, JSON, AsyncTransport, SyncTransport, _Config
+from ._resources import Batch, Chat, Emails, Events, Knowledge, Payments
+
+
+class Hatang:
+    """The Ha Tang API.
+
+    ``Hatang("ht_…")``, or set ``HATANG_API_KEY``. Every method returns the API's JSON as a dict and raises
+    ``HatangError`` when the call does not succeed. Use it as a context manager, or call ``close()``, to release
+    its connections.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        environment: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.Client] = None,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        config = _Config(api_key, base_url, environment, user_agent)
+        self.base_url = config.base_url
+        self._transport = SyncTransport(config, timeout, http_client)
+        request, text = self._transport.request, self._transport.text
+        self.emails: Emails[JSON, str] = Emails(request, text)
+        self.batch: Batch[JSON, str] = Batch(request, text)
+        self.knowledge: Knowledge[JSON, str] = Knowledge(request, text)
+        self.chat: Chat[JSON, str] = Chat(request, text)
+        self.payments: Payments[JSON, str] = Payments(request, text)
+        self.events: Events[JSON, str] = Events(request, text)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "Hatang":
+        return self
+
+    def __exit__(self, exc_type: Optional[Type[BaseException]], exc: Optional[BaseException], tb: Optional[TracebackType]) -> None:
+        self.close()
+
+
+class AsyncHatang:
+    """The Ha Tang API for asyncio (FastAPI, aiohttp…): the same namespaces as ``Hatang``, every method awaited."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        environment: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: Optional[httpx.AsyncClient] = None,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        config = _Config(api_key, base_url, environment, user_agent)
+        self.base_url = config.base_url
+        self._transport = AsyncTransport(config, timeout, http_client)
+        request, text = self._transport.request, self._transport.text
+        self.emails: Emails[Awaitable[JSON], Awaitable[str]] = Emails(request, text)
+        self.batch: Batch[Awaitable[JSON], Awaitable[str]] = Batch(request, text)
+        self.knowledge: Knowledge[Awaitable[JSON], Awaitable[str]] = Knowledge(request, text)
+        self.chat: Chat[Awaitable[JSON], Awaitable[str]] = Chat(request, text)
+        self.payments: Payments[Awaitable[JSON], Awaitable[str]] = Payments(request, text)
+        self.events: Events[Awaitable[JSON], Awaitable[str]] = Events(request, text)
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> "AsyncHatang":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.aclose()

hatang/_resources.py

@@ -0,0 +1,262 @@
+"""API namespaces, shared by the sync and async clients.
+
+Each method returns what the transport's ``request`` returns: the response dict for ``Hatang``, an awaitable of it
+for ``AsyncHatang``. Names follow ``@hatang/sdk`` in snake_case.
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, Callable, Dict, Generic, List, Mapping, Optional, Sequence, TypeVar, Union
+
+from ._client import Query, seg
+from .types import (
+    ChatProductOptions,
+    ChatPurchaseOptions,
+    ChatSubscriptionOptions,
+    CreateChatOrderOptions,
+    CreateEmailOptions,
+    CreatePaymentOptions,
+    KnowledgeDocumentInput,
+    Platform,
+    SendChatMessageOptions,
+)
+
+R = TypeVar("R")
+#: What text endpoints (CSV) return: ``str``, or an awaitable of it.
+S = TypeVar("S")
+Request = Callable[..., R]
+
+
+def _idempotency(key: Optional[str]) -> Optional[Dict[str, str]]:
+    return {"Idempotency-Key": key} if key else None
+
+
+def _encode_email(payload: Mapping[str, Any]) -> Dict[str, Any]:
+    """Attachments given as bytes travel base64-encoded, like the Node SDK's Buffers."""
+    body = dict(payload)
+    files = body.get("attachments")
+    if files:
+        body["attachments"] = [
+            {**a, "content": base64.b64encode(a["content"]).decode("ascii")} if isinstance(a.get("content"), (bytes, bytearray)) else dict(a)
+            for a in files
+        ]
+    return body
+
+
+class _Namespace(Generic[R, S]):
+    def __init__(self, request: Request[R], text: Callable[..., S]) -> None:
+        self._request = request
+        self._text = text
+
+
+class Emails(_Namespace[R, S]):
+    def send(self, payload: CreateEmailOptions, *, idempotency_key: Optional[str] = None) -> R:
+        """Send an email (or schedule it with ``scheduled_at``)."""
+        return self._request("POST", "/emails", _encode_email(payload), headers=_idempotency(idempotency_key))
+
+    def get(self, id: str) -> R:
+        return self._request("GET", f"/emails/{seg(id)}")
+
+    def list(self, *, limit: Optional[int] = None, after: Optional[str] = None, before: Optional[str] = None) -> R:
+        return self._request("GET", "/emails", query={"limit": limit, "after": after, "before": before})
+
+    def update(self, id: str, *, scheduled_at: str) -> R:
+        """Move a scheduled email."""
+        return self._request("PATCH", f"/emails/{seg(id)}", {"scheduled_at": scheduled_at})
+
+    def cancel(self, id: str) -> R:
+        """Cancel a scheduled email."""
+        return self._request("POST", f"/emails/{seg(id)}/cancel")
+
+
+class Batch(_Namespace[R, S]):
+    def send(self, payloads: Sequence[CreateEmailOptions]) -> R:
+        """Up to 100 emails in one call."""
+        return self._request("POST", "/emails/batch", [_encode_email(p) for p in payloads])
+
+
+class Knowledge(_Namespace[R, S]):
+    """The documents the AI assistant answers from, under your own ids."""
+
+    def upsert(self, id: str, document: KnowledgeDocumentInput) -> R:
+        return self._request("PUT", f"/chat/knowledge/documents/{seg(id)}", dict(document))
+
+    def batch(self, documents: Sequence[KnowledgeDocumentInput]) -> R:
+        """Several documents at once; each needs its ``external_id``."""
+        return self._request("POST", "/chat/knowledge/documents/batch", {"documents": [dict(d) for d in documents]})
+
+    def sync(self, collection: str, documents: Sequence[KnowledgeDocumentInput]) -> R:
+        """The collection then holds exactly these documents; unchanged ones are not re-indexed."""
+        return self._request("POST", f"/chat/knowledge/collections/{seg(collection)}/sync", {"documents": [dict(d) for d in documents]})
+
+    def get(self, id: str) -> R:
+        return self._request("GET", f"/chat/knowledge/documents/{seg(id)}")
+
+    def list(self, *, collection: Optional[str] = None, tag: Optional[str] = None, locale: Optional[str] = None, after: Optional[str] = None, limit: Optional[int] = None) -> R:
+        return self._request("GET", "/chat/knowledge/documents", query={"collection": collection, "tag": tag, "locale": locale, "after": after, "limit": limit})
+
+    def remove(self, id: str) -> R:
+        return self._request("DELETE", f"/chat/knowledge/documents/{seg(id)}")
+
+    def search(self, q: str, *, locale: Optional[str] = None, limit: Optional[int] = None) -> R:
+        """What the assistant would find for a question."""
+        return self._request("GET", "/chat/knowledge/search", query={"q": q, "locale": locale, "limit": limit})
+
+
+class Subscriptions(_Namespace[R, S]):
+    """Plans on the web, the App Store and Google Play, on the customer's profile."""
+
+    def upsert(self, platform: Platform, original_id: str, payload: ChatSubscriptionOptions) -> R:
+        """Create or update by platform and your / the store's id (Apple originalTransactionId, Play purchase
+        token). Sending the same state again changes nothing."""
+        return self._request("PUT", f"/chat/subscriptions/{platform}/{seg(original_id)}", dict(payload))
+
+    def list(self, *, external_user_id: Optional[str] = None, platform: Optional[Platform] = None, status: Union[str, Sequence[str], None] = None, limit: Optional[int] = None) -> R:
+        return self._request("GET", "/chat/subscriptions", query={"external_user_id": external_user_id, "platform": platform, "status": status, "limit": limit})
+
+    def for_customer(self, customer_id: str) -> R:
+        return self._request("GET", f"/chat/customers/{seg(customer_id)}/subscriptions")
+
+    def purchase_token(self, site_id: str, user_id: str) -> R:
+        """The app account token, from the API. ``hatang.purchase_token`` computes the same value locally."""
+        return self._request("GET", f"/chat/sites/{seg(site_id)}/purchase-token", query={"user_id": user_id})
+
+
+class Purchases(_Namespace[R, S]):
+    """One-time purchases: credit packs, unlocks, courses; refunds included."""
+
+    def upsert(self, platform: Platform, transaction_id: str, payload: ChatPurchaseOptions) -> R:
+        """Record or update by platform and your order id (web) or the store's transaction id."""
+        return self._request("PUT", f"/chat/purchases/{platform}/{seg(transaction_id)}", dict(payload))
+
+    def list(self, *, external_user_id: Optional[str] = None, platform: Optional[Platform] = None, limit: Optional[int] = None) -> R:
+        return self._request("GET", "/chat/purchases", query={"external_user_id": external_user_id, "platform": platform, "limit": limit})
+
+    def for_customer(self, customer_id: str) -> R:
+        return self._request("GET", f"/chat/customers/{seg(customer_id)}/purchases")
+
+
+class Customers(_Namespace[R, S]):
+    def list(self, *, q: Optional[str] = None, stage: Optional[str] = None, label: Optional[str] = None, owner_id: Optional[str] = None, channel: Optional[str] = None, limit: Optional[int] = None, after: Optional[str] = None) -> R:
+        return self._request("GET", "/chat/customers", query={"q": q, "stage": stage, "label": label, "owner_id": owner_id, "channel": channel, "limit": limit, "after": after})
+
+    def get(self, id: str) -> R:
+        return self._request("GET", f"/chat/customers/{seg(id)}")
+
+    def update(self, id: str, payload: Mapping[str, Any]) -> R:
+        """Name, email, phone, owner, lead stage, labels and custom ``fields``."""
+        return self._request("PATCH", f"/chat/customers/{seg(id)}", dict(payload))
+
+    def conversations(self, id: str) -> R:
+        return self._request("GET", f"/chat/customers/{seg(id)}/conversations")
+
+    def export_csv(self, query: Optional[Query] = None) -> S:
+        """Everyone matching the filters, as CSV text."""
+        return self._text("/chat/customers/export.csv", query)
+
+
+class Conversations(_Namespace[R, S]):
+    def list(self, *, status: Union[str, Sequence[str], None] = None, unanswered: Optional[bool] = None, limit: Optional[int] = None, after: Optional[str] = None, **filters: Any) -> R:
+        return self._request("GET", "/chat/conversations", query={"status": status, "unanswered": unanswered, "limit": limit, "after": after, **filters})
+
+    def get(self, id: str) -> R:
+        return self._request("GET", f"/chat/conversations/{seg(id)}")
+
+    def update(self, id: str, payload: Mapping[str, Any]) -> R:
+        """Assign, tag, resolve, hide."""
+        return self._request("PATCH", f"/chat/conversations/{seg(id)}", dict(payload))
+
+    def messages(self, id: str, *, after_seq: Optional[int] = None, limit: Optional[int] = None, include_private: Optional[bool] = None) -> R:
+        return self._request("GET", f"/chat/conversations/{seg(id)}/messages", query={"after_seq": after_seq, "limit": limit, "include_private": include_private})
+
+    def send(self, id: str, payload: SendChatMessageOptions, *, idempotency_key: Optional[str] = None) -> R:
+        """Reply as an agent, or add a private note."""
+        return self._request("POST", f"/chat/conversations/{seg(id)}/messages", dict(payload), headers=_idempotency(idempotency_key))
+
+    def send_products(self, id: str, product_ids: List[str], intro: Optional[str] = None) -> R:
+        """A product card (up to 10 products) with an optional intro line."""
+        body: Dict[str, Any] = {"product_ids": product_ids}
+        if intro:
+            body["intro"] = intro
+        return self._request("POST", f"/chat/conversations/{seg(id)}/products", body)
+
+
+class Products(_Namespace[R, S]):
+    def list(self, *, q: Optional[str] = None, category: Optional[str] = None, active: Optional[bool] = None, limit: Optional[int] = None, after: Optional[str] = None) -> R:
+        return self._request("GET", "/chat/products", query={"q": q, "category": category, "active": active, "limit": limit, "after": after})
+
+    def search(self, q: str, limit: Optional[int] = None) -> R:
+        return self._request("GET", "/chat/products/search", query={"q": q, "limit": limit})
+
+    def get(self, id: str) -> R:
+        return self._request("GET", f"/chat/products/{seg(id)}")
+
+    def create(self, payload: ChatProductOptions) -> R:
+        return self._request("POST", "/chat/products", dict(payload))
+
+    def update(self, id: str, payload: ChatProductOptions) -> R:
+        return self._request("PATCH", f"/chat/products/{seg(id)}", dict(payload))
+
+    def remove(self, id: str) -> R:
+        return self._request("DELETE", f"/chat/products/{seg(id)}")
+
+
+class Orders(_Namespace[R, S]):
+    def list(self, *, status: Optional[str] = None, customer_id: Optional[str] = None, conversation_id: Optional[str] = None, payment_status: Optional[str] = None, q: Optional[str] = None, limit: Optional[int] = None, after: Optional[str] = None) -> R:
+        return self._request("GET", "/chat/orders", query={"status": status, "customer_id": customer_id, "conversation_id": conversation_id, "payment_status": payment_status, "q": q, "limit": limit, "after": after})
+
+    def get(self, id: str) -> R:
+        return self._request("GET", f"/chat/orders/{seg(id)}")
+
+    def create(self, payload: CreateChatOrderOptions) -> R:
+        return self._request("POST", "/chat/orders", dict(payload))
+
+    def update(self, id: str, payload: Mapping[str, Any]) -> R:
+        return self._request("PATCH", f"/chat/orders/{seg(id)}", dict(payload))
+
+    def payment_link(self, id: str, *, expires_in: Optional[int] = None, send_card: Optional[bool] = None) -> R:
+        """A VietQR payment for the order's total; the card lands in the conversation unless ``send_card=False``."""
+        body = {k: v for k, v in {"expires_in": expires_in, "send_card": send_card}.items() if v is not None}
+        return self._request("POST", f"/chat/orders/{seg(id)}/payment-link", body)
+
+
+class Chat(Generic[R, S]):
+    """Support: customers, conversations, plans and purchases, products, orders."""
+
+    def __init__(self, request: Request[R], text: Callable[..., S]) -> None:
+        self.customers = Customers(request, text)
+        self.conversations = Conversations(request, text)
+        self.subscriptions = Subscriptions(request, text)
+        self.purchases = Purchases(request, text)
+        self.products = Products(request, text)
+        self.orders = Orders(request, text)
+
+
+class Payments(_Namespace[R, S]):
+    """VietQR payments, confirmed by your bank's transfer notification."""
+
+    def create(self, payload: CreatePaymentOptions, *, idempotency_key: Optional[str] = None) -> R:
+        return self._request("POST", "/payments", dict(payload), headers=_idempotency(idempotency_key))
+
+    def get(self, id: str) -> R:
+        return self._request("GET", f"/payments/{seg(id)}")
+
+    def list(self, *, status: Optional[str] = None, connection_id: Optional[str] = None, limit: Optional[int] = None, after: Optional[str] = None) -> R:
+        return self._request("GET", "/payments", query={"status": status, "connection_id": connection_id, "limit": limit, "after": after})
+
+    def cancel(self, id: str) -> R:
+        return self._request("POST", f"/payments/{seg(id)}/cancel")
+
+
+class Events(_Namespace[R, S]):
+    def send(self, event: str, *, contact_id: Optional[str] = None, email: Optional[str] = None, payload: Optional[Mapping[str, Any]] = None) -> R:
+        """Trigger automations waiting for this event, for one contact (by id or email)."""
+        body: Dict[str, Any] = {"event": event}
+        if contact_id:
+            body["contact_id"] = contact_id
+        if email:
+            body["email"] = email
+        if payload is not None:
+            body["payload"] = dict(payload)
+        return self._request("POST", "/events/send", body)

hatang/_version.py

@@ -0,0 +1 @@
+VERSION = "0.1.0"

hatang/helpers.py

@@ -0,0 +1,22 @@
+"""Values your backend computes itself, the same way Ha Tang's servers and the app SDKs do."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import uuid
+
+
+def identity_hash(user_id: str, identity_secret: str) -> str:
+    """The signature that makes a chat identity trusted: hex HMAC-SHA256 of the user id with the site's identity
+    secret (Ha Tang → Support → Channels → the site → Widget). Pass it as ``hash`` with ``userId`` to ``identify``
+    in the widget or the app SDKs; never send the secret to the browser or the app."""
+    return hmac.new(identity_secret.encode("utf-8"), user_id.encode("utf-8"), hashlib.sha256).hexdigest()
+
+
+def purchase_token(site_id: str, user_id: str) -> str:
+    """The app account token for one of your users: pass it as StoreKit ``appAccountToken`` / Google Play
+    ``obfuscatedAccountId`` so the stores' notifications reach that customer in Ha Tang. A UUID v5 of the user id
+    in the site's namespace; the app SDKs' ``purchaseToken`` gives the same value."""
+    namespace = uuid.uuid5(uuid.NAMESPACE_URL, f"hatang:site:{site_id}")
+    return str(uuid.uuid5(namespace, user_id))

hatang/types.py

@@ -0,0 +1,189 @@
+"""Typed request bodies, matching the REST API and ``@hatang/sdk``. Responses are plain dicts as the API sends them.
+
+Every key is optional to the type checker (``total=False``); the docstrings say which ones the API requires.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, TypedDict, Union
+
+Platform = Literal["web", "ios", "android"]
+SubscriptionStatus = Literal["trial", "active", "grace", "on_hold", "paused", "canceled", "expired", "refunded", "revoked"]
+PurchaseKind = Literal["consumable", "non_consumable", "non_renewing"]
+
+
+class ChatSubscriptionOptions(TypedDict, total=False):
+    """A plan your backend knows about. ``status`` is required."""
+
+    status: SubscriptionStatus
+    store_product_id: str | None
+    base_plan_id: str | None
+    product_id: str | None
+    #: The catalog product's SKU: how a plan sold on your own site finds its product.
+    sku: str | None
+    #: The user id you pass to ``identify`` in the chat: links the plan to the customer.
+    external_user_id: str | None
+    account_token: str | None
+    customer_id: str | None
+    auto_renew: bool | None
+    environment: Literal["production", "sandbox"]
+    started_at: str | None
+    current_period_end: str | None
+    canceled_at: str | None
+    amount: float | None
+    currency: str | None
+    #: What happened, for the customer's timeline (``renewed``, ``canceled``…), and when.
+    event: str
+    event_at: str
+
+
+class ChatPurchaseOptions(TypedDict, total=False):
+    """A one-time purchase (credit pack, unlock, course). ``store_product_id`` is required: the store's product
+    id, or on the web your own code for what was sold."""
+
+    store_product_id: str
+    kind: PurchaseKind
+    status: Literal["purchased", "refunded"]
+    product_id: str | None
+    sku: str | None
+    quantity: int
+    external_user_id: str | None
+    customer_id: str | None
+    environment: Literal["production", "sandbox"]
+    amount: float | None
+    currency: str | None
+    purchased_at: str | None
+    refunded_at: str | None
+
+
+class KnowledgeDocumentInput(TypedDict, total=False):
+    """A document the AI assistant answers from. ``title`` and ``content`` (Markdown, up to 200,000 characters)
+    are required."""
+
+    title: str
+    content: str
+    #: The page the document lives at, cited in answers.
+    url: str | None
+    #: Its language, such as ``vi`` or ``en``.
+    locale: str | None
+    tags: List[str]
+    #: A set you can sync as a whole (``knowledge.sync``).
+    collection: str | None
+    #: Your id for it, in ``knowledge.batch`` and ``knowledge.sync``.
+    external_id: str
+
+
+class Attachment(TypedDict, total=False):
+    """``filename`` and ``content`` are required; ``bytes`` content is base64-encoded for you."""
+
+    filename: str
+    content: Union[str, bytes]
+    content_type: str
+    content_id: str
+
+
+class Tag(TypedDict):
+    name: str
+    value: str
+
+
+class EmailTemplate(TypedDict, total=False):
+    id: str
+    variables: Dict[str, Union[str, int, float, bool, None]]
+
+
+class CreateEmailOptions(TypedDict, total=False):
+    """``to`` is required; ``from`` and ``subject`` too unless a ``template`` sets them. Pass ``from`` with
+    ``**{"from": …}`` or as a dict literal, since ``from`` is a Python keyword."""
+
+    to: Union[str, List[str]]
+    subject: str
+    html: str
+    text: str
+    template: EmailTemplate
+    cc: Union[str, List[str]]
+    bcc: Union[str, List[str]]
+    reply_to: Union[str, List[str]]
+    headers: Dict[str, str]
+    tags: List[Tag]
+    attachments: List[Attachment]
+    scheduled_at: str
+    topic_id: str
+
+
+class SendChatMessageOptions(TypedDict, total=False):
+    """``content`` is required. ``visibility="private"`` is an internal note the visitor never sees."""
+
+    content: str
+    visibility: Literal["public", "private"]
+    attachments: List[str]
+    sender_name: str
+    metadata: Dict[str, Any]
+
+
+class PaymentCustomer(TypedDict, total=False):
+    name: str
+    email: str
+    phone: str
+
+
+class CreatePaymentOptions(TypedDict, total=False):
+    """A VietQR payment. ``amount`` (VND) is required."""
+
+    amount: int
+    description: str
+    #: Your own transfer description (your order number): letters and digits, 6 to 20.
+    code: str
+    connection_id: str
+    expires_in: int
+    return_url: str
+    #: Your endpoint for this payment's IPN calls; check them with ``verify_ipn``.
+    ipn_url: str
+    customer: PaymentCustomer
+    metadata: Dict[str, Union[str, int, float, bool, None]]
+
+
+class ChatOrderItem(TypedDict, total=False):
+    """``name``, ``price`` and ``quantity`` are required."""
+
+    product_id: str | None
+    name: str
+    sku: str | None
+    variant: str | None
+    price: int
+    quantity: int
+
+
+class CreateChatOrderOptions(TypedDict, total=False):
+    """``items`` is required."""
+
+    conversation_id: str
+    customer_id: str
+    items: List[ChatOrderItem]
+    discount: int
+    shipping: int
+    shipping_address: Dict[str, Any]
+    note: str | None
+    status: str
+    invoice: bool
+    send_card: bool
+
+
+class ChatProductOptions(TypedDict, total=False):
+    """``name`` is required. ``prices`` holds the App Store / Google Play prices and store ids."""
+
+    name: str
+    sku: str | None
+    description: str | None
+    price: int
+    compare_at_price: int | None
+    image_url: str | None
+    url: str | None
+    category: str | None
+    stock: int | None
+    active: bool
+    kind: str
+    billing_period: str | None
+    trial_days: int | None
+    prices: List[Dict[str, Any]]
+    variants: List[Dict[str, Any]]

hatang/webhooks.py

@@ -0,0 +1,83 @@
+"""Checking what Ha Tang sends to your endpoints: webhook deliveries and payment IPN calls.
+
+Always pass the raw request body exactly as received (bytes or str), before any JSON parsing.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Dict, Mapping, Optional, Union
+
+from ._errors import HatangSignatureError
+
+RawBody = Union[bytes, bytearray, str]
+Headers = Mapping[str, Any]
+
+
+def _text(body: RawBody) -> str:
+    return body.decode("utf-8") if isinstance(body, (bytes, bytearray)) else body
+
+
+def _header(headers: Headers, name: str) -> Optional[str]:
+    getter = getattr(headers, "get", None)
+    for key in (name, name.title()):
+        value = getter(key) if getter else None
+        if value is not None:
+            break
+    else:
+        value = next((v for k, v in headers.items() if str(k).lower() == name), None)
+    if isinstance(value, (list, tuple)):
+        value = value[0] if value else None
+    return None if value is None else str(value)
+
+
+def verify_webhook(raw_body: RawBody, headers: Headers, secret: str, *, tolerance_sec: int = 300) -> bool:
+    """True when a webhook delivery is signed with your endpoint's ``whsec_…`` secret (Standard Webhooks /
+    Svix headers) and is no older than ``tolerance_sec`` (5 minutes by default, against replays)."""
+    msg_id = _header(headers, "svix-id") or _header(headers, "webhook-id")
+    ts = _header(headers, "svix-timestamp") or _header(headers, "webhook-timestamp")
+    sigs = _header(headers, "svix-signature") or _header(headers, "webhook-signature")
+    if not msg_id or not ts or not sigs:
+        return False
+    try:
+        sent = int(ts)
+    except ValueError:
+        return False
+    if abs(time.time() - sent) > tolerance_sec:
+        return False
+    key = base64.b64decode(secret[6:] if secret.startswith("whsec_") else secret)
+    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.{_text(raw_body)}".encode("utf-8"), hashlib.sha256).digest()).decode("ascii")
+    for part in sigs.split(" "):
+        version, _, sig = part.partition(",")
+        if version == "v1" and sig and hmac.compare_digest(sig, expected):
+            return True
+    return False
+
+
+def construct_webhook_event(raw_body: RawBody, headers: Headers, secret: str, *, tolerance_sec: int = 300) -> Dict[str, Any]:
+    """The verified event (``type``, ``created_at``, ``data``), or ``HatangSignatureError``."""
+    if not verify_webhook(raw_body, headers, secret, tolerance_sec=tolerance_sec):
+        raise HatangSignatureError("Webhook signature or timestamp is not valid")
+    event: Dict[str, Any] = json.loads(_text(raw_body))
+    return event
+
+
+def verify_ipn(raw_body: RawBody, signature: Optional[str], secret_key: str) -> bool:
+    """True when a payment IPN call matches its ``Hatang-Signature`` header: hex HMAC-SHA256 of the body with
+    your secret key (Payments settings → Integration keys, of the call's environment)."""
+    if not signature:
+        return False
+    expected = hmac.new(secret_key.encode("utf-8"), _text(raw_body).encode("utf-8"), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(signature.strip().lower(), expected)
+
+
+def construct_ipn_event(raw_body: RawBody, headers: Headers, secret_key: str) -> Dict[str, Any]:
+    """The verified IPN call (``data.status``, ``data.metadata``…), or ``HatangSignatureError``."""
+    if not verify_ipn(raw_body, _header(headers, "hatang-signature"), secret_key):
+        raise HatangSignatureError("Hatang-Signature does not match the body and secret key")
+    event: Dict[str, Any] = json.loads(_text(raw_body))
+    return event

hatang-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: hatang
+Version: 0.1.0
+Summary: Official Python SDK for Ha Tang (hatang.dev): support CRM, plans and purchases, AI knowledge, email, payments, webhooks.
+Project-URL: Homepage, https://hatang.dev
+Project-URL: Documentation, https://hatang.dev/docs/guides/sdks/python
+Project-URL: Source, https://github.com/sota-labs/hatang/tree/main/sdks/python
+Project-URL: Changelog, https://github.com/sota-labs/hatang/blob/main/sdks/python/CHANGELOG.md
+Author-email: Sota Labs <hello@hatang.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chat,crm,email,hatang,in-app purchases,support,vietqr,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Description-Content-Type: text/markdown
+
+# hatang
+
+The official Python SDK for [Ha Tang](https://hatang.dev): support CRM, plans and purchases on the customer's profile,
+the AI assistant's knowledge, email, VietQR payments and webhooks.
+
+```bash
+pip install hatang
+```
+
+Python 3.9+. Sync (`Hatang`) and asyncio (`AsyncHatang`) clients, typed request bodies.
+
+## Quick start
+
+```python
+from hatang import Hatang
+
+hatang = Hatang()  # reads HATANG_API_KEY; or Hatang("ht_…")
+
+# What a customer pays for, from your backend (web sales included).
+hatang.chat.subscriptions.upsert("web", "sub_123", {
+    "status": "active",
+    "sku": "PRO-1M",                    # finds the product in your catalog
+    "external_user_id": "user-42",      # the id you pass to identify() in the chat
+    "current_period_end": "2026-12-01T00:00:00Z",
+    "amount": 99000, "currency": "VND",
+})
+hatang.chat.purchases.upsert("web", "order_981", {
+    "store_product_id": "credits.300", "sku": "XU-300", "kind": "consumable",
+    "external_user_id": "user-42", "amount": 29000, "currency": "VND",
+})
+```
+
+asyncio (FastAPI, aiohttp…):
+
+```python
+from hatang import AsyncHatang
+
+async with AsyncHatang() as hatang:
+    hits = await hatang.knowledge.search("hoàn tiền", limit=3)
+```
+
+Every method returns the API's JSON as a `dict`. A call that does not succeed raises `HatangError` with `status_code`
+(0 when Ha Tang was not reached), `name` (`validation_error`, `not_found`…), `message`, and `retryable` (unreachable,
+429 or 5xx).
+
+## What is in it
+
+| Namespace | Methods |
+|---|---|
+| `chat.subscriptions` | `upsert`, `list`, `for_customer`, `purchase_token` |
+| `chat.purchases` | `upsert`, `list`, `for_customer` |
+| `chat.customers` | `list`, `get`, `update`, `conversations`, `export_csv` |
+| `chat.conversations` | `list`, `get`, `update`, `messages`, `send`, `send_products` |
+| `chat.products` | `list`, `search`, `get`, `create`, `update`, `remove` |
+| `chat.orders` | `list`, `get`, `create`, `update`, `payment_link` |
+| `knowledge` | `upsert`, `batch`, `sync`, `get`, `list`, `remove`, `search` |
+| `emails`, `batch` | `send`, `get`, `list`, `update`, `cancel`; `batch.send` |
+| `payments` | `create`, `get`, `list`, `cancel` |
+| `events` | `send` |
+
+## Helpers
+
+```python
+from hatang import identity_hash, purchase_token, construct_webhook_event, construct_ipn_event
+
+# Signed chat identity: send this as `hash` with userId to identify() in the widget or the app SDKs.
+identity_hash("user-42", IDENTITY_SECRET)
+
+# StoreKit appAccountToken / Google Play obfuscatedAccountId for one of your users.
+purchase_token("site_…", "user-42")
+
+# Webhooks (whsec_… secret) and payment IPN calls: pass the raw body, before JSON parsing.
+event = construct_webhook_event(request.body, request.headers, WEBHOOK_SECRET)
+ipn = construct_ipn_event(request.body, request.headers, SECRET_KEY)
+```
+
+Both raise `HatangSignatureError` when the signature does not match; `verify_webhook` / `verify_ipn` return a bool.
+
+## Configuration
+
+| Argument | Environment | Default |
+|---|---|---|
+| `api_key` | `HATANG_API_KEY` | required |
+| `base_url` | `HATANG_BASE_URL` | `https://api.hatang.dev` |
+| `environment` | `HATANG_ENVIRONMENT` | the key's own |
+| `timeout` | | 30 s |
+| `http_client` | | an `httpx.Client` / `httpx.AsyncClient` of your own (proxies, retries, tests) |
+
+Docs: [hatang.dev/docs](https://hatang.dev/docs/guides/sdks/python) · License: MIT

hatang-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+hatang/__init__.py,sha256=epToB2gBaRvt9rSDFwwmqnBOjycmue-_8SheDMExo48,837
+hatang/_client.py,sha256=I066Q6S_4O9Zw20tlQo-ClZTcCa2wAu1jCkFy-65kik,5471
+hatang/_errors.py,sha256=ivX2UrVqsdH8cg5RkYIb-dHAVhtLv-XQAY7Wd39wrMc,900
+hatang/_hatang.py,sha256=2yUYjblfSwzr5IosAHwQEb71KR1bHcna0KpNhiXhKpA,3259
+hatang/_resources.py,sha256=uhV9ZCU44APnWUv1djmVZse_022dGKns7PPO18XN-2c,13458
+hatang/_version.py,sha256=CpXi3jGlx23RvRyU7iytOMZrnspdWw4yofS8lpP1AJU,18
+hatang/helpers.py,sha256=-2nazAkSF0zY8-x2SUCLYW4fIsmXo2Won8CHnf2AB3w,1147
+hatang/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hatang/types.py,sha256=yfkRPR4usyCCeSpK85cUJYJaUuJbV3nDf237kC-g6fQ,5537
+hatang/webhooks.py,sha256=Lyoq_SBJm5hHNXwyMHWRGjvQyP6tcoNLbhI6qgwKrnU,3660
+hatang-0.1.0.dist-info/METADATA,sha256=QXWymCQFjTqmVf3ULfuNqMVziOXbRm-m-JCCKAPP4BI,4482
+hatang-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hatang-0.1.0.dist-info/licenses/LICENSE,sha256=AGhx7zYemIO7k3AXES_KqzvSBYQFmz906OI3mf1SpZE,1071
+hatang-0.1.0.dist-info/RECORD,,

hatang-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hatang-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Sota Labs
+
+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.