satzet 1.0.0__py3-none-any.whl

satzet/__init__.py

@@ -0,0 +1,34 @@
+"""Python client for a wadeno-server WhatsApp gateway.
+
+    from satzet import Client
+
+    wa = Client("http://localhost:8000", api_key=os.environ["WADENO_API_KEY"])
+    wa.session("default").send_text("628123456789", "halo")
+
+READ THIS BEFORE YOUR FIRST SEND. This gateway will not message somebody who has never written to
+it — that refusal is the whole reason the number does not get banned. `Session.consent(to)` is how
+you vouch for a recipient who signed up elsewhere, and first contacts are held to roughly ten a
+day. See `GateError` for what to do about each kind of refusal.
+"""
+
+from .client import Client, Session
+from .errors import (
+    AuthError,
+    ConflictError,
+    GateError,
+    NotConfiguredError,
+    SATZETError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Client",
+    "Session",
+    "SATZETError",
+    "GateError",
+    "AuthError",
+    "ConflictError",
+    "NotConfiguredError",
+    "__version__",
+]

satzet/client.py

@@ -0,0 +1,580 @@
+"""The gateway, as one object.
+
+WHAT THIS IS. A thin wrapper over the HTTP API: base URL, credentials, and a translator that turns
+the server's status codes into exceptions worth catching. Deliberately NOT a generated client with
+a class per response — the API is small enough that dicts are easier to read than a hierarchy to
+learn, and :meth:`Client.request` reaches anything not wrapped here.
+
+WHAT IT CANNOT DO FOR YOU. The consent rule. This gateway will not message somebody who has never
+written to it, and no client library changes that — see :meth:`Session.consent`.
+
+Zero dependencies: the standard library's ``urllib`` is enough for JSON over HTTP, and a client
+this small should not drag ``requests`` into somebody's lockfile.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Literal, Mapping, MutableMapping
+
+from .errors import (
+    AuthError,
+    ConflictError,
+    GateError,
+    NotConfiguredError,
+    SATZETError,
+)
+
+__all__ = ["Client", "Session"]
+
+JsonDict = dict[str, Any]
+
+
+class Client:
+    """A wadeno-server gateway.
+
+    >>> from satzet import Client
+    >>> wa = Client("http://localhost:8000", api_key=os.environ["WADENO_API_KEY"])
+    >>> wa.session("default").send_text("628123456789", "halo")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        token: str | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        """
+        :param base_url: where the gateway is, e.g. ``http://localhost:8000``.
+        :param api_key: a session's database-backed key, ``WADENO_API_KEY``, or ``WADENO_API_KEYS``.
+        :param token: a Bearer token from :meth:`login`. Needed for autopilot and key management,
+            which refuse an API key however wide its scope.
+        :param timeout: seconds. Generous by default — a send waits out the gate's deliberate
+            spacing before it returns.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.token = token
+        self.timeout = timeout
+
+    # ---------------------------------------------------------------- sessions
+
+    def session(self, session_id: str) -> "Session":
+        """One account, and everything that hangs off it."""
+        return Session(self, session_id)
+
+    def sessions(self, *, archived: bool = False) -> JsonDict:
+        """Every registered account, with its live state."""
+        return self.request("GET", "/v1/sessions", query={"archived": "1"} if archived else None)
+
+    def create_session(self, session_id: str, **options: Any) -> JsonDict:
+        """Register a session. **Does not connect anything** — call ``start()`` next."""
+        return self.request("POST", "/v1/sessions", {"id": session_id, **options})
+
+    # ---------------------------------------------------------------- credentials
+
+    def health(self) -> JsonDict:
+        """Liveness. The only route that needs no credential."""
+        return self.request("GET", "/health")
+
+    def login(self, username: str, password: str) -> JsonDict:
+        """Sign in, and keep the token for the rest of this client's life.
+
+        Note the asymmetry with the API key: the key answers "may this caller in", the token
+        answers "who is it", and a few routes need the second question answered.
+        """
+        result = self.request("POST", "/v1/auth/login", {"username": username, "password": password})
+        if result.get("token"):
+            self.token = str(result["token"])
+        return result
+
+    # ---------------------------------------------------------------- webhook
+
+    def webhook(self) -> JsonDict:
+        """Where inbound events go, and whether they are arriving."""
+        return self.request("GET", "/v1/webhook")
+
+    def set_webhook(self, **config: Any) -> JsonDict:
+        """Point the webhook somewhere.
+
+        PATCH-like despite the verb: a field you leave out keeps its value, and an explicit
+        ``None`` clears it. That is what lets a form which — correctly — never displays the secret
+        be saved without unsigning the webhook.
+        """
+        return self.request("PUT", "/v1/webhook", config)
+
+    def test_webhook(self) -> JsonDict:
+        """Fire one event and report what the receiver said.
+
+        200 either way — the request succeeded in finding out. It exists because a webhook that is
+        quietly being refused looks exactly like one that is working.
+        """
+        return self.request("POST", "/v1/webhook/test")
+
+    # ---------------------------------------------------------------- transport
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        body: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+    ) -> JsonDict:
+        """Anything this class does not wrap.
+
+        The escape hatch, and a first-class part of the design rather than an admission: the
+        gateway has around a hundred routes and this library wraps the ones people actually call.
+        Everything else — channels, leads, Sheets exports, the assistant — is one line away, with
+        the same authentication and the same error translation.
+
+        >>> wa.request("GET", "/v1/sessions/default/leads", query={"status": "new"})
+        """
+        url = self.base_url + path
+        if query:
+            clean = {k: v for k, v in query.items() if v is not None}
+            if clean:
+                url += "?" + urllib.parse.urlencode(clean)
+
+        headers: MutableMapping[str, str] = {
+            "Accept": "application/json",
+            "x-api-key": self.api_key,
+        }
+        if self.token:
+            # Both credentials, deliberately. The gateway reads identity BEFORE it decides
+            # authentication, so a key WITH a token is that person rather than an anonymous
+            # machine — which is what keeps a signed-in operator's assistant history their own.
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        data: bytes | None = None
+        if body is not None:
+            data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+
+        request = urllib.request.Request(url, data=data, headers=dict(headers), method=method.upper())
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return _decode(response.status, response.read())
+        except urllib.error.HTTPError as exc:
+            # An HTTPError IS the response for every 4xx and 5xx, so the body — which carries the
+            # gate's `code` — is read from it rather than lost to a generic message.
+            raise _translate(exc.code, exc.read()) from None
+        except urllib.error.URLError as exc:
+            # Never reached the server, so there is no status and no code. Distinguished from a
+            # refusal because the fix is a network or a URL rather than a request.
+            raise SATZETError(f"could not reach the gateway at {self.base_url}: {exc.reason}") from None
+
+
+class Session:
+    """One WhatsApp account, and everything that hangs off it.
+
+    THE ORDER THAT MATTERS, for anybody arriving from a gateway with no safety policy:
+
+    1. :meth:`start` and scan the QR from :meth:`qr`, once, per number.
+    2. :meth:`consent` for anybody who has not written to you first.
+    3. :meth:`send_text`.
+
+    Skip step 2 and step 3 raises :class:`~satzet.errors.GateError` with ``no-consent``, forever.
+    That is the feature working.
+    """
+
+    def __init__(self, client: Client, session_id: str) -> None:
+        self.client = client
+        self.id = session_id
+
+    def _path(self, suffix: str = "") -> str:
+        return f"/v1/sessions/{self.id}{suffix}"
+
+    def call(
+        self,
+        method: str,
+        suffix: str = "",
+        body: Mapping[str, Any] | None = None,
+        query: Mapping[str, Any] | None = None,
+    ) -> JsonDict:
+        """Anything on this session that this class does not wrap — channels, leads, status."""
+        return self.client.request(method, self._path(suffix), body, query)
+
+    # ---------------------------------------------------------------- linking
+
+    def get(self) -> JsonDict:
+        """The record plus the gate's snapshot."""
+        return self.call("GET")
+
+    def status(self) -> JsonDict:
+        """What the connection is doing right now. Poll this while linking."""
+        return self.call("GET", "/status")
+
+    def start(self, pair_phone: str | None = None) -> JsonDict:
+        """Start linking. **Returns immediately — it does not wait for the scan.**
+
+        For an unlinked device the connection only completes once somebody picks up their phone, so
+        awaiting it would hang for minutes. Poll :meth:`qr` afterwards.
+
+        :param pair_phone: ask for an 8-character pairing code for this number instead of a QR —
+            easier to read out over the phone than a picture.
+        """
+        return self.call("POST", "/start", {"pairPhone": pair_phone} if pair_phone else {})
+
+    def qr(self) -> JsonDict | None:
+        """The QR or pairing code to show somebody, or ``None`` once there is nothing to scan.
+
+        ``None`` is how a polling loop learns it can stop: the underlying 404 means either "already
+        linked" or "no offer yet", and :meth:`status` says which. A code older than about 20 seconds
+        still comes back, marked ``stale`` — a screen that empties itself every twenty seconds is
+        worse than one that says "fetching a new code".
+        """
+        try:
+            return self.call("GET", "/qr")
+        except SATZETError as exc:
+            if exc.status == 404:
+                return None
+            raise
+
+    def stop(self) -> JsonDict:
+        """Disconnect, keep the link."""
+        return self.call("POST", "/stop")
+
+    def delete(self, *, purge: bool = False) -> JsonDict:
+        """Unlink the number, or forget the session entirely.
+
+        **Two different acts.** Without ``purge`` the device is unlinked from the WhatsApp account
+        and the record survives, so a new number can be scanned into the same slot. With ``purge``
+        the record, the journal, the contacts, the leads, the schedules and the credentials on disk
+        all go. Both are irreversible.
+        """
+        return self.call("DELETE", query={"purge": "1"} if purge else None)
+
+    # ---------------------------------------------------------------- session API keys
+
+    def api_keys(self) -> JsonDict:
+        """Live key metadata for this session. Requires ``client.login()`` and PostgreSQL."""
+        return self.call("GET", "/keys")
+
+    def create_api_key(self, name: str, scope: Literal["full", "mcp"] = "full") -> JsonDict:
+        """Create a key restricted to this session. Save ``secret`` securely: it is shown once.
+
+        ``full`` supports sending; ``mcp`` permits the MCP integration routes without sending.
+        Requires a signed-in person; an existing API key alone cannot create another one.
+        """
+        return self.call("POST", "/keys", {"name": name, "scope": scope})
+
+    def revoke_api_key(self, key_id: str) -> JsonDict:
+        """Revoke a key immediately. Requires a signed-in person."""
+        return self.call("DELETE", f"/keys/{urllib.parse.quote(key_id, safe='')}")
+
+    # ---------------------------------------------------------------- sending
+
+    def consent(self, to: str) -> JsonDict:
+        """Record that somebody agreed to be contacted, outside WhatsApp.
+
+        **THE MOST IMPORTANT METHOD IN THIS LIBRARY, and the one nobody expects to need.** This
+        gateway's whole defence against being banned is that it does not contact people who did not
+        ask: bans come from user reports, and reports come from unsolicited contact. A recipient who
+        has never written in is refused by :meth:`send_text` with ``no-consent``, permanently.
+
+        So call this for the one recipient you are willing to vouch for — a signup form, an order,
+        a person who gave you their number — and then send. Note what it is NOT: there is no bulk
+        version, and first contacts are held to roughly ten a day. Three hundred leads is a month of
+        outreach, deliberately.
+        """
+        return self.call("POST", "/consent", {"to": to})
+
+    def send_text(self, to: str, text: str, *, quote: str | None = None) -> JsonDict:
+        """Send a text message.
+
+        ``to`` is a phone number in international form (``628123456789``) or a full JID. A national
+        number (``0812…``) is refused rather than guessed at — it addresses nobody.
+
+        Raises :class:`~satzet.errors.GateError` when the safety policy refuses. Catch it and ask
+        which kind: ``deferred`` means wait ``retry_after_ms``, ``rejected`` means retrying will
+        never help.
+
+        ``quote`` is optional: a WhatsApp message id from THIS conversation, which pins the reply
+        to it — the grey "reply" bar the app shows. A 404 means the gateway's journal no longer has
+        it; a 400 means it belongs to another chat, which is refused because a quote carries a copy
+        of the original text.
+
+        :returns: ``id`` is WhatsApp's message id; ``delayedMs`` is how long the gate held it,
+            because the spacing is jittered on purpose.
+        """
+        body: JsonDict = {"to": to, "text": text}
+        # Omitted rather than sent as None when nobody asked, so an ordinary send is the same
+        # request it was before quoting existed.
+        if quote is not None:
+            body["quote"] = quote
+        return self.call("POST", "/messages", body)
+
+    def send_image(
+        self,
+        to: str,
+        *,
+        url: str | None = None,
+        image: str | bytes | None = None,
+        path: str | Path | None = None,
+        caption: str | None = None,
+    ) -> JsonDict:
+        """Send an image by URL, by base64, or from a local file.
+
+        16 MB cap however it arrives. An uncaptioned image is invisible to the duplicate rule — the
+        caption is the only comparable part of one.
+        """
+        body: JsonDict = {"to": to}
+        if path is not None:
+            body["image"] = base64.b64encode(Path(path).read_bytes()).decode("ascii")
+        elif isinstance(image, bytes):
+            body["image"] = base64.b64encode(image).decode("ascii")
+        elif image is not None:
+            body["image"] = image
+        elif url is not None:
+            body["url"] = url
+        else:
+            raise SATZETError("give one of `url`, `image` or `path`")
+        if caption is not None:
+            body["caption"] = caption
+        return self.call("POST", "/messages/image", body)
+
+    def delete_message(self, to: str, message_id: str) -> JsonDict:
+        """Delete a message for everyone.
+
+        ``to`` is required alongside the id: a message id does not say which chat it lives in, and a
+        revoke pointed at the wrong chat silently deletes nothing.
+        """
+        return self.call("POST", f"/messages/{message_id}/delete", {"to": to})
+
+    def pin_message(self, to: str, message_id: str, duration: str | int = "day") -> JsonDict:
+        """Pin a message for everyone in the chat.
+
+        :param duration: ``day``, ``week``, ``month``, or a raw number of seconds — though the
+            recipient then sees a countdown they could not have set themselves.
+        """
+        return self.call("POST", f"/messages/{message_id}/pin", {"to": to, "duration": duration})
+
+    def unpin_message(self, to: str, message_id: str) -> JsonDict:
+        return self.call("POST", f"/messages/{message_id}/unpin", {"to": to})
+
+    # ---------------------------------------------------------------- many recipients, and later
+
+    def broadcast(self, to: list[str], text: str) -> JsonDict:
+        """Start a broadcast. **Returns a job immediately — poll it with :meth:`broadcast_job`.**
+
+        A hundred recipients through the gate is several minutes of deliberate spacing, so this does
+        not wait. Recipients are de-duplicated by the gateway, so a bare number and the same number
+        as a JID cost one send rather than two.
+
+        One broadcast per session at a time; a second raises :class:`~satzet.errors.ConflictError`
+        carrying the job already running, so a reloaded page can re-attach.
+        """
+        return self.call("POST", "/broadcasts", {"to": list(to), "text": text})
+
+    def broadcast_job(self, job_id: str) -> JsonDict:
+        return self.call("GET", f"/broadcasts/{job_id}")
+
+    def cancel_broadcast(self, job_id: str) -> JsonDict:
+        """Stops between recipients, never mid-send."""
+        return self.call("POST", f"/broadcasts/{job_id}/cancel")
+
+    def broadcasts(self) -> JsonDict:
+        """Jobs, newest first. In memory, so not resumed after a restart."""
+        return self.call("GET", "/broadcasts")
+
+    def schedule(
+        self,
+        to: str,
+        text: str,
+        *,
+        send_at: str | int | None = None,
+        delay_ms: int | None = None,
+        note: str | None = None,
+    ) -> JsonDict:
+        """Send a message at a moment of your choosing.
+
+        Unlike :meth:`send_text`, this IS retried when the gate defers — it is persisted, and given
+        up on only outside its grace window. A message that comes due more than an hour late is
+        recorded as ``missed`` rather than sent, because "9am Tuesday" stops meaning anything by
+        noon.
+
+        The session does not have to be connected to schedule. Consent, however, is checked NOW as
+        well as at send time — so a cold recipient is a 400 here rather than a queue of refusals
+        nobody is awake to read.
+
+        :param send_at: an ISO timestamp (``2026-08-30T09:00:00+07:00``) or epoch milliseconds.
+        :param delay_ms: an alternative to ``send_at``, for a caller with no clock to convert with.
+        """
+        body: JsonDict = {"to": to, "text": text}
+        if send_at is not None:
+            body["sendAt"] = send_at
+        if delay_ms is not None:
+            body["delayMs"] = delay_ms
+        if note is not None:
+            body["note"] = note
+        return self.call("POST", "/schedules", body)
+
+    def schedules(self, **filters: Any) -> JsonDict:
+        """What is waiting. Filters: ``status``, ``limit``."""
+        return self.call("GET", "/schedules", query=filters)
+
+    def cancel_schedule(self, schedule_id: str) -> JsonDict:
+        """Only while it is still pending — 409 once it has gone."""
+        return self.call("DELETE", f"/schedules/{schedule_id}")
+
+    # ---------------------------------------------------------------- what the gateway heard
+
+    def chats(self) -> JsonDict:
+        """Conversations, newest first, with unread counts.
+
+        This is what the GATEWAY saw, not the contents of the account: a linked device is never sent
+        the history, so anything older than the link is unreachable. The journal keeps the last 2000
+        messages. Telegram conversations are merged in already.
+        """
+        return self.call("GET", "/chats")
+
+    def thread(self, chat: str, **options: Any) -> JsonDict:
+        """One thread, oldest first. Page backwards with the ``at`` of the oldest message as ``before``."""
+        return self.call("GET", f"/chats/{urllib.parse.quote(chat, safe='')}/messages", query=options)
+
+    def mark_seen(self, chat: str) -> JsonDict:
+        """Clear the unread count.
+
+        **Sends no read receipt** — the other side still sees one tick. Telling somebody their
+        message has been read because an operator glanced at a dashboard would be a lie told on
+        their behalf.
+        """
+        return self.call("POST", f"/chats/{urllib.parse.quote(chat, safe='')}/seen")
+
+    def messages(self, **filters: Any) -> JsonDict:
+        """The send log, newest first. Filters: ``direction``, ``state``, ``kind``, ``limit``."""
+        return self.call("GET", "/messages", query=filters)
+
+    def stats(self, **options: Any) -> JsonDict:
+        """Counts and an hourly series. ``hours`` defaults to 24."""
+        return self.call("GET", "/stats", query=options)
+
+    # ---------------------------------------------------------------- contacts and policy
+
+    def contacts(self) -> JsonDict:
+        """Saved names merged with harvested numbers and consent.
+
+        Three separate things, kept apart on purpose. ``consent`` is the one people mean when they
+        ask "can I message them" — a saved contact is a NAME and never a permission — and
+        ``nameSource`` says whether a name came from you or from what the person calls themselves,
+        which is self-declared and unverified.
+        """
+        return self.call("GET", "/contacts")
+
+    def save_contact(self, phone: str, **fields: Any) -> JsonDict:
+        """Create or update one contact. ``name``, ``tag``, ``note``."""
+        return self.call("POST", "/contacts", {"phone": phone, **fields})
+
+    def import_contacts(self, **body: Any) -> JsonDict:
+        """Import many: ``from_known=True`` is spelled ``fromKnown=True`` here, or pass ``contacts``.
+
+        Existing entries are never overwritten — your name for a number outranks any learned
+        automatically.
+        """
+        return self.call("POST", "/contacts/import", body)
+
+    def policy(self) -> JsonDict:
+        """What the outbound policy currently thinks of this number.
+
+        Where to look when sends start coming back 429: whether the number is parked, how hot it is,
+        and when it comes back.
+        """
+        return self.call("GET", "/policy")
+
+    def drafts(self) -> JsonDict:
+        """Replies the assistant suggested and nobody has acted on.
+
+        **Not an outbox.** Nothing drains it and there is no route that sends one: read the draft,
+        put it in your composer, and send it with :meth:`send_text` — which is judged by the gate
+        exactly as a message you typed, because it is one.
+        """
+        return self.call("GET", "/drafts")
+
+    # ---------------------------------------------------------------- autopilot
+
+    def autopilot(self) -> JsonDict:
+        """The automatic-reply switch, the consequences, and what is stopping it running.
+
+        ``ready`` is three separate facts rather than one boolean, and ``last`` is the field worth
+        watching: when a model call fails nothing reaches the send path, so there is no error
+        anywhere and the operator is left looking at a switch that says on while customers go
+        unanswered. ``last.reason`` is usually the model vendor's own sentence.
+        """
+        return self.call("GET", "/autopilot")
+
+    def set_autopilot(self, **settings: Any) -> JsonDict:
+        """Turn automatic replies on or off.
+
+        **Needs a signed-in person** — call :meth:`Client.login` first, because an API key is refused
+        here however wide its scope. Switching it ON additionally requires echoing back the
+        acknowledgement version from :meth:`autopilot`, so a client cannot agree to consequences it
+        was never handed::
+
+            state = session.autopilot()
+            session.set_autopilot(
+                enabled=True,
+                persona="Admin toko, ramah, jawab singkat.",
+                dailyReplyCap=20,
+                acknowledge={"version": state["consent"]["version"]},
+            )
+
+        Set the daily cap LOW on the first day and read the first twenty replies before trusting it
+        with a second number.
+        """
+        return self.call("PUT", "/autopilot", settings)
+
+
+# ---------------------------------------------------------------- decoding
+
+
+def _decode(status: int, raw: bytes) -> JsonDict:
+    if not raw:
+        return {}
+    try:
+        decoded = json.loads(raw)
+    except json.JSONDecodeError:
+        raise SATZETError(
+            f"the gateway answered {status} with a body that is not JSON: {raw[:200]!r}",
+            status=status,
+        ) from None
+    return decoded if isinstance(decoded, dict) else {"data": decoded}
+
+
+def _translate(status: int, raw: bytes) -> SATZETError:
+    """The exception a refusal deserves.
+
+    A body that is not JSON at all is its own diagnosis: something in front of the gateway — a
+    proxy, a login page, a tunnel — answered instead of it. Say so, rather than reporting an empty
+    message that reads as the gateway failing silently.
+    """
+    try:
+        body = json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        body = {}
+    if not isinstance(body, dict):
+        body = {}
+
+    message = body.get("error") or (
+        f"the gateway answered {status} with a body that is not JSON: {raw[:200]!r}"
+        if raw and not body
+        else f"the gateway answered {status}"
+    )
+    code = body.get("code")
+    kwargs: dict[str, Any] = {"status": status, "code": str(code) if code else None, "body": body}
+
+    if status in (422, 429):
+        return GateError(str(message), **kwargs)
+    if status in (401, 403):
+        return AuthError(str(message), **kwargs)
+    if status == 409:
+        return ConflictError(str(message), **kwargs)
+    if status == 501:
+        return NotConfiguredError(str(message), **kwargs)
+    return SATZETError(str(message), **kwargs)

satzet/errors.py

@@ -0,0 +1,152 @@
+"""What the gateway refused, as exceptions worth catching separately.
+
+Branch on ``code``, never on ``str(exc)``. The prose is written for a person and somebody will
+reword it; the code is the contract.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+__all__ = [
+    "SATZETError",
+    "GateError",
+    "AuthError",
+    "ConflictError",
+    "NotConfiguredError",
+]
+
+
+class SATZETError(Exception):
+    """Anything that went wrong: a refusal, a bad request, or a gateway nobody could reach.
+
+    ``status`` is 0 when the request never arrived, which is the one case with no ``code``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str | None = None,
+        body: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body: Mapping[str, Any] = body or {}
+
+
+class GateError(SATZETError):
+    """The outbound safety policy refused a send.
+
+    THIS IS THE ERROR TO WRITE CODE AGAINST. Coming from a gateway with no safety policy the
+    natural assumption is that a send either works or errors; here it can also be refused for a
+    reason, and the right response differs by which reason.
+
+    ``deferred``          429. Temporary — wait ``retry_after_ms`` and try again.
+    ``rejected``          422. Terminal — **retrying will never help**.
+    ``about_recipient``   this ONE person. In a loop, skip them and carry on.
+    ``about_number``      your WhatsApp number itself. In a loop, STOP: everything queued behind
+                          this collects an identical refusal, and each one is another danger
+                          signal against the number you are trying to protect.
+    ``about_text``        the message text, or the fan-out this send would cause.
+
+    The commonest by far is ``no-consent``: this gateway will not message somebody who has never
+    written to it. See :meth:`satzet.Session.consent`.
+    """
+
+    #: Properties of the NUMBER — everything else queued behind this is refused the same way.
+    ABOUT_NUMBER = frozenset({"paused", "unhealthy", "daily-quota", "new-contact-quota"})
+    #: Properties of the PERSON — the next recipient may well be fine.
+    ABOUT_RECIPIENT = frozenset({"no-consent", "reply-window-closed"})
+    #: Properties of the TEXT, or of the fan-out.
+    ABOUT_TEXT = frozenset({"duplicate-content", "status-audience-too-large"})
+
+    @property
+    def gate(self) -> str | None:
+        """``reject`` (terminal) or ``defer`` (temporary)."""
+        value = self.body.get("gate")
+        return str(value) if value is not None else None
+
+    @property
+    def retry_after_ms(self) -> int | None:
+        """How long to wait, on a defer."""
+        value = self.body.get("retryAfterMs")
+        return int(value) if value is not None else None
+
+    @property
+    def deferred(self) -> bool:
+        return self.status == 429
+
+    @property
+    def rejected(self) -> bool:
+        return self.status == 422
+
+    @property
+    def about_recipient(self) -> bool:
+        return self.code in self.ABOUT_RECIPIENT
+
+    @property
+    def about_number(self) -> bool:
+        return self.code in self.ABOUT_NUMBER
+
+    @property
+    def about_text(self) -> bool:
+        return self.code in self.ABOUT_TEXT
+
+    @property
+    def should_stop_batch(self) -> bool:
+        """Whether a loop over many recipients should abandon the rest.
+
+        The same rule this gateway's own broadcast queue applies, kept in one place rather than
+        remembered at every call site: a refusal about the NUMBER or the TEXT applies to everybody
+        left, so grinding on collects one identical refusal per recipient — and, worse, one more
+        danger signal per copy.
+        """
+        return not self.about_recipient
+
+
+class AuthError(SATZETError):
+    """The credential was missing, wrong, or aimed somewhere it may not go.
+
+    ``401`` — no credential, or one this gateway does not recognise. Check the key you pasted.
+    ``403`` — a VALID credential in the wrong place, and ``code`` says which:
+              ``key-scope``   this key is scoped to ``mcp`` and the path needs ``full``. ``scope``
+                              and the key's name in the message say which of your keys answered.
+              ``needs-login`` the route needs a signed-in person, and an API key will never do
+                              however wide its scope. Call ``login()`` and pass the token.
+    """
+
+    @property
+    def scope(self) -> str | None:
+        value = self.body.get("scope")
+        return str(value) if value is not None else None
+
+    @property
+    def needs_login(self) -> bool:
+        return self.code == "needs-login"
+
+
+class ConflictError(SATZETError):
+    """409 — the request is fine, the gateway's state is not where the request needs it.
+
+    Four causes, and they are not the same problem: the session has no live WhatsApp connection
+    (``not_connected``); a broadcast is already running on this session, and the running job comes
+    back in ``body`` so a reloaded page can re-attach; a scheduled message has already gone, and
+    nothing recalls a sent message; this session already has three live API keys.
+    """
+
+    @property
+    def not_connected(self) -> bool:
+        return "not connected" in self.message
+
+
+class NotConfiguredError(SATZETError):
+    """501 — the route exists, the feature is not configured on this install.
+
+    The assistant with no model key, lead search with no Google Maps key, Sheets with no service
+    account, minted API keys with no database. The message names the variable to set. Deliberately
+    not a 404 or a 500: nothing is missing and nothing is broken.
+    """

satzet-1.0.0.dist-info/METADATA

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: satzet
+Version: 1.0.0
+Summary: Python client for a wadeno-server WhatsApp gateway: sending, consent, broadcasts, schedules and the journal.
+Keywords: api-client,gateway,satzet,whatsapp
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# satzet (Python)
+
+Python client for a [wadeno-server](../..) WhatsApp gateway.
+
+Requires Python 3.10+. **No dependencies** — the standard library's `urllib` is enough for JSON over
+HTTP, and a client this small should not put `requests` in your lockfile.
+
+## Install
+
+While this lives in the gateway's own repository rather than on PyPI:
+
+```bash
+pip install ./wadeno-server/clients/python
+```
+
+Published, it would be the ordinary one line:
+
+```bash
+pip install satzet
+```
+
+## Send a message
+
+```python
+import os
+from satzet import Client
+
+wa = Client("http://localhost:8000", api_key=os.environ["WADENO_SESSION_API_KEY"])
+session = wa.session("default")
+
+sent = session.send_text("628123456789", "Halo, pesanan Anda sudah kami terima.")
+print(sent["id"])
+```
+
+## Per-session API keys
+
+Configure PostgreSQL with `DATABASE_URL` and apply the gateway's database schema. Creating a new
+session automatically issues its own `full` key:
+
+```python
+operator = Client("http://localhost:8000", os.environ["WADENO_API_KEY"])
+created = operator.create_session("orders")
+if "apiKey" not in created:
+    raise RuntimeError("Configure PostgreSQL to issue session keys")
+
+# Save this secret in your integration's secret store now. It is shown only once.
+integration = Client("http://localhost:8000", created["apiKey"]["secret"])
+orders = integration.session(created["session"]["id"])
+orders.status()
+```
+
+For an existing session, sign in before creating or managing keys:
+
+```python
+operator.login(os.environ["WADENO_USERNAME"], os.environ["WADENO_PASSWORD"])
+orders_admin = operator.session("orders")
+issued = orders_admin.create_api_key("Orders SDK")  # scope defaults to full
+integration = Client("http://localhost:8000", issued["secret"])
+integration.session("orders").status()
+
+metadata = orders_admin.api_keys()  # no secret or hash in this response
+orders_admin.revoke_api_key(issued["key"]["id"])  # this key stops working immediately
+```
+
+Save `issued["secret"]` securely; the database stores its SHA-256 hash and cannot reveal the secret
+again. Keys only access their own session, including WhatsApp and Telegram routes; another session
+raises `AuthError`. An integration key alone cannot manage keys. Use
+`create_api_key("MCP integration", "mcp")` for MCP access without sending; `full` permits sending
+subject to the usual consent and outbound rules. A session can have three live keys. Revoking one
+frees a slot.
+
+## Read this before your first send
+
+**This gateway will not message somebody who has never written to it.** That refusal is not a bug
+and not a configuration mistake — it is the whole reason the number does not get banned. Bans come
+from user reports, and reports come from unsolicited contact.
+
+For a recipient who agreed somewhere else — a signup form, an order, somebody who handed over their
+number — vouch for them first:
+
+```python
+session.consent("628123456789")          # records the agreement
+session.send_text("628123456789", "Halo!")
+```
+
+There is no bulk version of `consent()`, deliberately, and first contacts are held to roughly ten a
+day. Three hundred leads is a month of outreach. That is the feature working.
+
+## Handling refusals
+
+A send can fail in ways that are not errors in your code, and the right response differs by which:
+
+```python
+import time
+from satzet import GateError
+
+try:
+    session.send_text(phone, text)
+except GateError as error:
+    if error.deferred:
+        # 429. Temporary — your number is out of quota, parked, or being paced.
+        time.sleep(error.retry_after_ms / 1000)
+    elif error.about_recipient:
+        # 422 `no-consent`. This one person. The next recipient may be fine.
+        pass
+    else:
+        # 422 about the TEXT, or a refusal about the number. Retrying will not help.
+        raise
+```
+
+Looping over many recipients, `should_stop_batch` answers that in one attribute — it applies the
+same rule the gateway's own broadcast queue does:
+
+```python
+for phone in recipients:
+    try:
+        session.send_text(phone, text)
+    except GateError as error:
+        if error.should_stop_batch:
+            break        # about the number or the text: everybody left gets the same refusal
+        continue         # about this person: skip them
+```
+
+Better still, hand the list to the gateway and let it pace itself:
+
+```python
+job = session.broadcast(recipients, text)
+progress = session.broadcast_job(job["id"])
+```
+
+## The exceptions
+
+| Class                | When                                                                    |
+| -------------------- | ----------------------------------------------------------------------- |
+| `GateError`          | 422/429 — the safety policy refused. The one to write code against.     |
+| `AuthError`          | 401 (unrecognised key) / 403 (valid key, wrong place)                   |
+| `ConflictError`      | 409 — not connected, broadcast already running, schedule already sent   |
+| `NotConfiguredError` | 501 — the feature has no key or no database on this install             |
+| `SATZETError`        | everything else, including a gateway nobody could reach (`status` 0)    |
+
+All of them carry `status`, `code` and the decoded `body`. **Branch on `code`, never on the
+message** — the prose is written for a person and will be reworded.
+
+## Anything not wrapped
+
+The gateway has around a hundred routes; this library wraps the ones people actually call. The rest
+is one line away, with the same authentication and the same error translation:
+
+```python
+leads = wa.request("GET", "/v1/sessions/default/leads", query={"status": "new"})
+session.call("POST", "/status/text", {"text": "Buka sampai jam 9"})
+```
+
+See [`openapi.yaml`](../../openapi.yaml) for every route.
+
+## Autopilot needs a person
+
+Turning on automatic replies is refused for an API key however wide its scope, and switching it on
+means echoing back an acknowledgement version that only `autopilot()` hands out — so a client cannot
+agree to consequences it was never shown:
+
+```python
+wa.login("operator", password)
+
+state = session.autopilot()
+session.set_autopilot(
+    enabled=True,
+    persona="Admin toko, ramah, jawab singkat.",
+    dailyReplyCap=20,
+    acknowledge={"version": state["consent"]["version"]},
+)
+```
+
+Set the cap low on day one and read the first twenty replies before trusting it with a second
+number.
+
+## Tests
+
+Seventeen tests against a stub gateway, including key issuance, revocation, and session credentials:
+
+```bash
+python -m unittest discover -s tests -v
+```

satzet-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+satzet/__init__.py,sha256=qwC9OImQ7qNPxDy4V-BqZsjryVWZZS3c_7ByF0ea8cE,961
+satzet/client.py,sha256=5epw_uj-Bwq5wNn3yucWa33NNgRORU-o3XMwhCmDg64,25966
+satzet/errors.py,sha256=7pyjeZDfxTiLLyXqelC2jmkHUtmLAC06pDP1K01I3E8,5953
+satzet/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+satzet-1.0.0.dist-info/METADATA,sha256=aUDAmLw33RB23oaaAEyqCOdTXRaniA2f-2DxEy7BnQU,6919
+satzet-1.0.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+satzet-1.0.0.dist-info/RECORD,,

satzet-1.0.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