hatang 0.1.0__tar.gz

hatang-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+.mypy_cache/
+.pytest_cache/
+__pycache__/
+uv.lock

hatang-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to the `hatang` Python package are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-31
+
+### Added
+- First release: `Hatang` (sync) and `AsyncHatang` (asyncio) clients over httpx, with `HatangError` (`status_code`,
+  `name`, `message`, `retryable`).
+- `chat.subscriptions`, `chat.purchases`, `chat.customers`, `chat.conversations`, `chat.products`, `chat.orders`,
+  `knowledge`, `emails`, `batch`, `payments`, `events.send`; typed request bodies in `hatang.types`.
+- `identity_hash`, `purchase_token`, `verify_webhook` / `construct_webhook_event`, `verify_ipn` /
+  `construct_ipn_event`, checked against values from Ha Tang's servers and the Node SDK.

hatang-0.1.0/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.

hatang-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,89 @@
+# 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/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "hatang"
+version = "0.1.0"
+description = "Official Python SDK for Ha Tang (hatang.dev): support CRM, plans and purchases, AI knowledge, email, payments, webhooks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Sota Labs", email = "hello@hatang.dev" }]
+keywords = ["hatang", "support", "crm", "chat", "email", "vietqr", "webhooks", "in-app purchases"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Communications :: Email",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25,<1"]
+
+[project.urls]
+Homepage = "https://hatang.dev"
+Documentation = "https://hatang.dev/docs/guides/sdks/python"
+Source = "https://github.com/sota-labs/hatang/tree/main/sdks/python"
+Changelog = "https://github.com/sota-labs/hatang/blob/main/sdks/python/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "mypy>=1.10"]
+
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hatang"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+strict = true
+files = ["src/hatang"]

hatang-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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()